flake8-plugin-utils

1.3.3 · active · verified Sun Apr 12

flake8-plugin-utils is a Python package providing base classes and utility functions to simplify the creation of custom plugins for the Flake8 linter. It aims to reduce boilerplate and offer helpful tools for AST (Abstract Syntax Tree) analysis within Flake8 plugins. The current version is 1.3.3, released on 2022-01-14, with a moderate release cadence based on contributions.

Warnings

breaking When using `flake8-plugin-utils` with typing (e.g., MyPy), the `Plugin` and `Visitor` classes are generic. If your plugin does not have any custom configuration, you must explicitly inherit from `Plugin[None]` and `Visitor[None]` to avoid type-checking errors.
Fix: Change `class MyPlugin(Plugin):` to `class MyPlugin(Plugin[None]):` and `class MyVisitor(Visitor):` to `class MyVisitor(Visitor[None]):` if no custom config is used. Otherwise, use your config class as the type parameter (e.g., `Plugin[MyConfig]`).
gotcha Flake8 plugins are registered via `setuptools` entry points. Incorrectly configuring the `entry_points` in your `setup.py` or `pyproject.toml` can lead to your plugin not being detected or conflicting with other plugins. Ensure your entry point is unique and correctly points to your plugin class.
Fix: Verify your `setup.py` contains an `entry_points` section like `{'flake8.extension': ['X = your_package.your_module:YourPluginClass']}`. The 'X' should be your plugin's unique error code prefix (e.g., 'X100', 'Y200').
gotcha When developing and testing Flake8 plugins, ensure you understand how Flake8 handles configuration files and local plugins. Issues can arise if configuration sections for uninstalled plugins are left in `.flake8`, `setup.cfg`, or `pyproject.toml`.
Fix: Manually remove any orphaned configuration sections related to uninstalled plugins from your Flake8 configuration files. Use `flake8 --isolated` during testing to ensure only command-line options are considered, or specify a clean config file.

Install

pip install flake8-plugin-utils Install stable version

Imports

Error
```
from flake8_plugin_utils import Error
```
Visitor
```
from flake8_plugin_utils import Visitor
```
Plugin
```
from flake8_plugin_utils import Plugin
```

assert_error

from flake8_plugin_utils import assert_error

assert_not_error

from flake8_plugin_utils import assert_not_error

Quickstart

This quickstart demonstrates how to define a custom Flake8 error, a visitor to detect specific AST patterns (here, the use of 'footgun' as a variable name), and a minimal plugin integrating these components. It also shows a basic test using `assert_error`.

from flake8_plugin_utils import Error, Visitor, Plugin, assert_error
import ast

# Define a custom error
class MyError(Error):
    code = 'X100'
    message = 'Avoid using the name {thing}'

# Define a custom visitor
class MyVisitor(Visitor):
    def visit_Name(self, node: ast.Name):
        if node.id == 'footgun':
            self.report(node, thing=node.id)

# Define the plugin (without configuration for simplicity)
class MyPlugin(Plugin[None]):
    name = 'flake8-myplugin'
    version = '0.1.0'
    visitors = [MyVisitor]

# Example of testing the plugin (typically in a test suite)
def test_my_plugin_error():
    src = """import os\nfootgun = 1"""
    assert_error(MyVisitor, src, MyError, row=2, col=0, thing='footgun')

# To run the linter (outside this snippet, typically from command line)
# flake8 --isolated --select=X100 my_code.py
# or integrate via entry points in setup.py

view raw JSON →