pytest-eo

pytest --eo is a strict quality gate in the spirit of Qulice, built from ready-made tools. The plugin runs the tools, reads their reports, and shows each tool as a separate test; its own rules cover only tests and suppressions.

The Elegant Objects rules enabled so far, most of them from pyeo and the rest from its sibling packages:

mypy runs with explicit-override and warn_unreachable on top of --strict: an @override must override a real method, every overriding method must say so, and code that can never run is an error. Python 3.11 has no typing.override; import it from typing_extensions.

The package also brings a flake8 plugin of its own, with rules in the spirit of "Angry Tests" for the files pytest collects (test_*.py, *_test.py):

More rules of its own cover every file, tests or not:

As in Qulice, which rejects plain JUnit assertions, a test asserts through a Hamcrest matcher, never through a plain assert; ruff's S101 stays on in tests too. PyHamcrest comes with the package:

from hamcrest import assert_that, equal_to


def test_checks_the_whole_directory_by_default(tmp_path: Path) -> None:
    assert_that(
        Project(EoTable(tmp_path / "pyproject.toml"), tmp_path).paths(),
        equal_to((".",)),
        "Project doesnt check the whole directory by default",
    )

A rule may be suppressed on one line only, with a reason: # noqa: PEO200 - pytest.Item is mutable by design, or # ruff: ignore[unused-import] - re-exported for plugins. eo::suppressions enforces it:

ruff already rejects a bare # noqa (PGH004), a bare # type: ignore (PGH003) and an unused # noqa for its own codes (RUF100).

The configuration is bundled with the package (src/pytest_eo/config/) and cannot be overridden by a project. A project may only say what to check and what to skip:

[tool.eo]
paths = ["src", "tests"]    # default: src and tests, if they exist
exclude = ["generated/"]

Usage

pip install 'pytest-eo==0.5.1'
pytest --eo

Without --eo the plugin does nothing. Pin an exact version: every version of the rules is a version of the package, so pip installs new rules only when the version in the requirement changes.

Claude Code hooks

This repository runs the gate on every Claude Code session that works in it: after Claude edits a .py, .toml, .ini or .cfg file, and again before it finishes. When the gate is red, the findings go back to Claude and it has to fix them. If the gate is still red after one retry, Claude may stop, and you see a warning instead.

To get the same in another project:

1. Install pytest-eo into the project's .venv.
2. Copy .claude/hooks/eo-gate.sh into the same place in that project and make it executable.
3. Copy the hooks block of .claude/settings.json into that project's .claude/settings.json, merging it with what is already there.
4. Commit both files, so everyone who opens the project with Claude Code gets the gate, and run /hooks once in an open session to load them.

Development

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
make check

make check runs the tests and pytest --eo on the plugin itself; Rultor merges on it. make coverage measures lines and branches, counting the pytest subprocesses of the end-to-end tests too, and writes coverage.xml, which GitHub Actions sends to Codecov on every push and pull request.

pyproject.toml on main always says version = "0.0.0"; a real version exists only in a tag. To release, comment in any issue, with the version in backticks, since Rultor reads nothing else:

@rultor release, tag is `0.3.0`

Rultor writes the version into pyproject.toml, runs make check, commits the result on a side branch and pushes only the tag. GitHub Actions builds that tag and uploads it to PyPI through Trusted Publishing, so no token is stored anywhere. Every change to the rules or the bundled configuration ships in a release: raise the minor number for a new or stricter rule and the patch number for a fix.