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.
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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.920 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.
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
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.