pyrigor

Catches the class of bug type checkers structurally cannot: a NamedTuple/keyword-only-argument/return-value-usage rule set for Python, inspired by safety-critical coding guidelines from other languages.

• Enforced rules catching real, silent bugs mypy strict mode passes clean
• Validated against real, public codebases: CPython's stdlib, Home Assistant, mypy, requests, hypothesis, abseil-py
• Checks an 18,187-file real-world codebase in under a minute
• Drop-in pre-commit integration, or run standalone

The tool pyrigor complements Python's tooling ecosystem. It does not try to replace it. If an established tool such as Pylint, Ruff, or a type checker already provides an adequate check, pyrigor will not duplicate that rule. Instead, pyrigor focuses on gaps where it can add distinct value.

Table of Contents

• The problem, in one example
• Usage
• Adding pyrigor to your own project
• What this is
• Status
• Guidelines
• Engineering and CI
• Philosophy
• Contributing
• Acknowledgements
• Contact
• License

The problem, in one example

The Mars Climate Orbiter was lost because two teams silently disagreed about units. The code for that class of bug would still get past mypy today.

Thrust = NewType("Thrust", float)
FuelMass = NewType("FuelMass", float)


def compute_burn_time(*, thrust: Thrust, fuel_mass: FuelMass) -> float: ...


# Both floats. Nothing about a bare float stops this from running,
# type-checking cleanly, and silently swapping the two values.
compute_burn_time(thrust=fuel_mass, fuel_mass=thrust)

This is pyrigor's PYR201 rule, NewType for same-typed values at risk of being swapped. It is documented today, not yet enforced. What pyrigor already catches, right now:

$ pyrigor launch_sequence.py
launch_sequence.py:12:1: PYR402 Function 'compute_burn_time' has
positional parameters; all parameters should be keyword-only
(keyword-only-arguments)

Usage

pip install pyrigor
pyrigor path/to/file.py [path/to/another.py ...]

Every rule marked enforced in guidelines/RULES.md runs automatically. A violation exits non-zero and prints path:line:col: PYRxxx message (symbolic-name).

Run pyrigor --version to check the installed version. Use --select=CODE,CODE to restrict checking to specific rules, for example pyrigor --select=PYR401,keyword-only-arguments path/. Use --ignore=CODE,CODE to exclude specific rules instead, running every other one. Both may be combined — --ignore removes codes from --select's set (or from every rule, if --select is omitted). The codes may be given as the full code, the bare number, or the symbolic name, the same as suppression comments. An unrecognised code exits immediately with an error naming it, as does a --select/--ignore combination that leaves no rules to check. Use --exclude PATH to omit a file or directory and everything below it. Repeat the option to exclude multiple paths. This exclusion is applied by pyrigor itself, independently of any pre-commit file filter.

PYR402 can be fixed explicitly after reviewing the planned change:

pyrigor --fix --select PYR402 path/
pyrigor --diff --select=PYR402 path/

--fix writes only the selected safe fixes and reports changed files. The --diff flag previews the same changes without writing. Fixer modes require explicit PYR402 selection; ordinary linting remains read-only. Both --select PYR402 and --select=PYR402 are accepted.

In diagnostic mode, exit code 1 means findings were reported. In fix mode, it means at least one source-file write failed. Each writing error names the file and operating system error on stderr. Other files are still processed, and only successful writes print Fixed. Successful fix runs exit 0. Usage errors exit 2. That includes a file name that the v2 diagnostics schema cannot represent, which stops the run before any file is read.

For the machine-readable editor or tooling integration, use --output-format=json. It emits one JSON document containing kept and suppressed findings, selected-rule metadata, tool identity, operational errors and a file count. Both JSON and human locations use 1-based Unicode code-point columns. See guidelines/JSON_DIAGNOSTICS.md for the contract and schema.

To suppress a specific violation, add a same-line comment with a reason:

def f(weight, bias):  # pyrigor PYR402 # matches a fixed external API
    ...

Codes may be given as the full code (PYR402), the bare number (402) or the rule's symbolic name (keyword-only-arguments). Multiple codes: # pyrigor 402,403 # reason. A suppression comment without a reason is ignored, and a warning is printed. Suppressed findings are counted per rule in the summary (PYR402: 1 suppressed), not silently discarded.

When stacking with another tool's own suppression comment on the same line (# nosec, # complexipy: ignore, ...), put pyrigor's own comment last — # nosec # pyrigor PYR402 # reason. The pyrigor comment must come after any other tool's comment, since its reason captures to the end of the line.

A suppression comment may also go on the line directly above the finding, or on any line in its primary span. For functions, that span runs from def or async def through the signature colon. A comment elsewhere in the function body does not suppress a signature finding. Assignment and call findings span the whole statement. The line above is useful when the mandatory reason would not fit on the starting line:

# pyrigor PYR402 # long test names plus a mandatory reason need more room
def apply_correction_for_the_pytest_fixture_injection_case(weight, bias): ...

Same-line comments continue to work. On wrapped statements, comments on any primary-span line work too.

Adding pyrigor to your own project

Add pyrigor to your own .pre-commit-config.yaml as a pinned, remote hook, the same way you would add ruff or black:

- repo: https://github.com/jarl-hoyem/pyrigor
  rev: v0.13.1
  hooks:
    - id: pyrigor
      args: [--exclude, generated]

Pin rev: to a real, released tag, not main. Check the release page for the latest version.

Show it in your own README:

[![Checked with pyrigor](https://img.shields.io/badge/checked%20with-pyrigor-blue)](https://github.com/jarl-hoyem/pyrigor)

Seeing violations in your editor

The tool pyrigor writes file:line:column: message, which most editors parse without needing a plugin. Configuring your existing tools beats installing another one.

In PyCharm, add a File Watcher under Settings, Tools, File Watchers:

On macOS and Linux the program path is $ProjectFileDir$/.venv/bin/pyrigor.

Two settings are not straightforward. The Show console: Never matters because pyrigor exits 1 whenever it finds anything, so any other value opens a console on every save. And Output filters is not a plain text field, it needs the browse button next to it, otherwise the value is silently discarded.

Findings then appear in the Problems view, clickable, as you save.

Other editors read the same lines. In Vim or Neovim, makeprg=pyrigor\ % with errorformat=%f:%l:%c:\ %m fills the quickfix list from :make. In Emacs, M-x compile running pyrigor . needs no configuration at all, because compilation mode already recognises this format. In Visual Studio Code, a task in .vscode/tasks.json whose problemMatcher pattern is ^(.+):(\d+):(\d+): (.+)$ fills the Problems panel, and that file is normally committed, so it reaches everyone on the project. Sublime Text takes the same expression as a build system's file_regex.

The text line is the lowest common denominator. Where an editor can consume structured output, --output-format=json carries more: severity, raw byte ranges, code-point ranges, enclosing symbols and selected-rule metadata. An integration can show ranges and colour them by severity. Findings currently carry an empty fixes list.

What this is

Python's failure modes are often silent: implicit type coercion, positional-argument swaps between same-typed parameters, mutable default arguments, float equality checks and tuple-unpacking that "type-checks" while being semantically wrong are all real, tool-catchable classes of bugs that slip past mypy, pylint and ruff's default rule sets.

pyrigor is a set of guidelines, with real, working tooling enforcing them today, growing as more rules are built out.

Status

Early stage.

See guidelines/RULES.md for the full, generated list of every rule and whether it is enforced yet.

• Guideline documentation
• Standalone AST-based checkers (pre-commit local hooks)
• Editor integration (deferred until real demand exists, see #152)

Guidelines

See guidelines/ for the full list. Each guideline has a rule ID, rationale, example and — once implemented — a link to its enforcing check.

guidelines/RULES.md has a generated table of every rule and whether it is enforced yet — generated from the real guideline docs and CHECKERS, never hand-maintained, so it cannot drift the way this table once did.

Engineering and CI

CI runs the exact same pre-commit configuration used locally (just check runs pre-commit run --all-files), so local and CI checks cannot silently drift apart. Every push and pull request against main builds across Ubuntu, macOS and Windows, and Python 3.11 through 3.15, after uv lock --check confirms the lockfile is current.

The gate includes strict typing across three checkers (mypy, pyright and ty), 100% branch-coverage enforcement and the security and quality checks listed in the badges above. Every run also builds the wheel and source distribution and smoke-tests them directly. Installing and running the packaged artefact rather than only the editable source checkout and runs pyrigor against the Python standard library to confirm it does not crash on real code.

Mutation testing runs in its own Docker container, as a non-root user matching the calling user's ID so it can write to the bind-mounted checkout. It gates on a maximum number of surviving mutants rather than a bare score percentage, since a percentage can hide new survivors while the total mutant count also grows.

On release, the build is smoke-tested against a large, real external codebase (Home Assistant's core) before publishing to PyPI through trusted publishing, with no long-lived API token involved. Every workflow's action references are pinned to a commit SHA rather than a mutable tag, checkout steps do not persist credentials unless the job needs to push, and jobs run under least-privilege token permissions.

Philosophy

Prefer explicit over implicit. Make illegal states unrepresentable. Do not rely on convention or code review where a tool can enforce correctness instead.

The tool pyrigor is prescriptive by design: each guideline does not just flag a risky pattern, it commits to one specific, verified fix. This is a deliberate choice, not an oversight — a codebase where every developer independently improvises their own fix for the same problem is exactly the inconsistency pyrigor exists to close.

Contributing

Participation is governed by the Code of Conduct.

1. Every change starts with an issue. Check open issues labeled ready for a well-scoped starting point, or open a new one.
2. Adding a new rule? Follow guidelines/ADDING_A_RULE.md step by step.
3. Run just check before pushing.
4. Open a Pull Request.

See CONTRIBUTING.md for full setup and workflow details.

Feedback

Evaluating pyrigor for your own project? Open an issue and tell the team about your use case — the maintainers want to use real adoption signals to drive priorities.

Acknowledgements

The tool pyrigor's own rules draw directly on real, external sources, not invented in isolation: Steve McConnell's Code Complete, the OSSF Secure Coding Guide for Python, and Google's Python Style Guide. Built on the shoulders of the real, open source tooling, it runs alongside every day: ruff, pylint, mypy, pyright, and pytest, among others credited throughout this project's own guideline docs.

Contact

Created and maintained by jarl-hoyem. For questions or ideas, open an issue.

License

MIT