flake8-stepdown

A flake8 plugin that enforces top-down (newspaper-style) function ordering in Python modules.

This is inspired by Robert C. Martin's "Clean Code" stepdown rule: High-level logic first, details later. When reading a module, callers should appear before callees, so you can read the code from top to bottom like a newspaper article.

Violation codes

Installation

pip install flake8-stepdown

The plugin registers itself with flake8 automatically. Verify it's installed:

flake8 --version

You should see flake8-stepdown in the list of installed plugins.

Usage

As a flake8 plugin

Just run flake8 as usual, the plugin will report TDP001 violations:

flake8 your_module.py

Standalone CLI

The package also provides a stepdown command with three subcommands:

# Report violations
stepdown check your_module.py

# Show a unified diff of the proposed reordering
stepdown diff your_module.py

# Rewrite files in place
stepdown fix your_module.py

Use -v / --verbose to show mutual recursion info on stderr.

Development

Prerequisites

• UV (Python package manager)

Setup

uv sync

Linting

./lint.sh

Testing

uv run pytest

Tests are organized by pipeline stage (test_parser.py, test_graph.py, test_rewriter.py, etc.). The rewriter uses snapshot testing: tests/fixtures/ contains input Python files exercising various scenarios (bottom-up ordering, mutual recursion, decorators, etc.), and tests/snapshots/ contains the expected output after rewriting. The test suite asserts correctness against snapshots, idempotency, and syntax validity.

Robustness testing

A separate script tests the plugin against real-world Python projects (click, httpx, rich, attrs, typer, pendulum, pydantic-settings) to detect crashes and code corruption:

bash tests/robustness/run_robustness.sh

For each project, the script:

1. Clones the repo and installs it alongside flake8-stepdown
2. Runs stepdown check and verifies it doesn't crash
3. Runs the project's test suite (baseline)
4. Runs stepdown fix and validates the rewritten code compiles
5. Re-runs the test suite and checks for regressions

See tests/robustness/projects.json to configure the list of target projects.

Pre-commit hooks

Pre-commit hooks are installed automatically. To run manually:

uv run pre-commit run --all-files

CI

GitHub Actions runs linting, type checking, and tests on every push to main and on pull requests.

Publishing to PyPI

This project uses trusted publishing via GitHub Actions.

To publish a new version:

1. Bump the version with uv version --bump patch (or minor/major)
2. Update __version__ in flake8_stepdown/__init__.py to match
3. Create a GitHub release with a tag matching the version (e.g., v0.1.0)
4. The publish workflow will automatically build and upload to PyPI

First-time setup: Configure a trusted publisher on PyPI under your project's settings (Publishing tab). Use publish.yml as the workflow name and publish as the environment name.

Contributing

See CONTRIBUTING.md for code style, conventions, and development workflow.