Registry / testing / flake8-plugin-utils

flake8-plugin-utils

library1.3.3pypypi✓ verified 29d ago

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.

testing

pip install flake8-plugin-utils

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FLAKE8-PLUGIN-UTIL

flake8-plugin-utils

testingpythonv1.3.3

Install

1.5s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Error

✓ from flake8_plugin_utils import Error

✗ from flake8_plugin_utils import Error

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

Debug

Known issues

breakingWhen 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]`).

affects: >=1.1.0

gotchaFlake8 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').

affects: All

gotchaWhen 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.

affects: All

Upgrade

Version history

1.3.3latest on PyPI · released Jun 26, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/afonasev/flake8-plugin-utils ↗

packagehttps://pypi.org/project/flake8-plugin-utils/ ↗

homepagehttps://pypi.org/project/flake8-plugin-utils ↗