pytest-flake8

pytest-flake8 wires flake8’s style and lint checks directly into a pytest run. Enable it with a single --flake8 flag and every collected .py file becomes its own pytest test item, so style violations are reported and fail the build exactly like any other test failure — no separate lint step or CI job required.

Results are cached against each file’s modification time, so unchanged files are skipped on subsequent runs and only newly edited files are re-checked. Per-glob flake8-ignore rules, configurable max line length, max complexity, and other flake8 options are all exposed through familiar pytest ini settings, and any flake8 plugins already installed in the environment are picked up automatically.

What You Get

• A --flake8 CLI flag that activates checking for the current pytest run with no extra configuration file
• One pytest test item per checked .py file, so failures appear inline with normal test results and respect pytest’s -k/-m filtering
• Cached pass/fail state keyed on file mtime, avoiding redundant re-checks of unchanged files on repeat runs
• Ini-based configuration (flake8-ignore, flake8-max-line-length, flake8-max-complexity, flake8-show-source, flake8-statistics, flake8-extensions) instead of a bespoke config format
• Automatic pickup of any flake8 plugins already installed in the test environment

Common Use Cases

• Gating CI builds on style violations without maintaining a separate lint pipeline stage
• Getting fast local feedback on style issues thanks to mtime-based result caching
• Rolling flake8 enforcement into a legacy codebase gradually using per-glob flake8-ignore rules
• Keeping the project’s entire quality bar — tests and style — behind one pytest command

Under The Hood

Architecture The plugin is a single module (pytest_flake8.py, ~230 lines) registered through the pytest11 entry point in pyproject.toml, so pytest auto-loads it with no explicit -p flag. pytest_addoption wires the --flake8 CLI flag and the flake8-* ini options; pytest_configure reads those options onto the config object once per session; pytest_collect_file turns each matching .py file into a Flake8File node that collects a single Flake8Item, whose runtest() builds a fresh flake8.main.application.Application(), redirects its stdout/stderr into in-memory buffers, and raises a custom Flake8Error if result_count is nonzero. A small Ignorer class parses the flake8-ignore ini lines into (glob, codes) tuples matched against each file via fnmatch. Cache reads/writes go through pytest’s built-in config.cache, keyed by file path and mtime. The design is a thin, single-responsibility bridge between two existing tools rather than a system with independent abstractions — the flake8 Application class is the one dependency the whole plugin is built around.

Tech Stack Pure Python, requires-python >= 3.10, with exactly two runtime dependencies: flake8 >= 4.0 and pytest >= 7.0. The build uses setuptools.build_meta with setuptools_scm for version derivation from git tags, plus a coherent.licensed build-time hook (part of the jaraco “skeleton” project template this repo is generated from) that injects license metadata at build time. Optional extras split cleanly by purpose: doc (Sphinx + furo + rst.linker), check (pytest-checkdocs, pytest-ruff), cover (pytest-cov), type (pytest-mypy), and enabler (pytest-enabler) — all dev-tooling extras, no runtime web framework, database, or deployment target since this ships purely as a PyPI-distributed pytest plugin.

Code Quality tests/test_flake8.py (~180 lines) exercises the plugin through pytest’s own pytester fixture, spinning up nested pytest runs and asserting on stdout output and pass/fail counts, alongside direct unit tests of the Ignorer glob-matching logic; a version-gated xfail handles a breaking change introduced in flake8 6.0. ruff.toml and .flake8 configs are present and a check extra wires in pytest-ruff/pytest-checkdocs, but a mypy.ini exists alongside a comment noting mypy checks are currently disabled (referencing an upstream skeleton issue), and the source itself carries no inline type hints. CI runs via GitHub Actions (.github/workflows/main.yml) and a tox.ini matrix. Error handling is a single purpose-built Flake8Error exception with no silently swallowed failures.

API Design Installing the package is the entire integration step — pytest --flake8 works immediately via pytest11 auto-discovery, with no conftest.py or explicit plugin registration needed. All configuration rides on pytest’s existing ini-file mechanism rather than a new config format, so anyone already familiar with pytest has no new surface to learn. The one rough edge is the flake8-ignore glob-and-codes mini-syntax, which is bespoke and only briefly documented in the README, and the mtime-based caching behavior (silently skipping previously-passed files) has confused users enough to earn its own FAQ entry with a --cache-clear workaround.