pyrigor

Disciplined Python patterns for catching bugs that type checkers and standard linters miss — inspired by safety-critical coding guidelines from other languages, adapted for a language and ecosystem they were not written for.

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 ...]

PYR301, PYR401, PYR402, PYR403, PYR405, and PYR406 are enforced today. A violation exits non-zero and prints path:line:col: PYR40x message (symbolic-name).

Run pyrigor --version to check the installed version. Use --only=CODE,CODE to restrict checking to specific rules, for example pyrigor --only=PYR401,keyword-only-arguments path/. The Codes may be given as the full code, the bare number, or the symbolic name, the same as suppression comments. An unrecognized code exits immediately with an error naming it.

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 violations 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. Pyrigor’s own comment must come after any other tool’s, since its reason captures to the end of the line.

A suppression comment may also go on the line directly above the violation, or anywhere within a multi-line statement’s own span — useful when a long, descriptive name plus the mandatory reason would not fit on the violating line itself:

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

The same-line still works exactly as before — these are additional locations, not a replacement.

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.7.3
  hooks:
    - id: pyrigor

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

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 collects a set of guidelines — and, over time, tooling to enforce them — aimed at closing those gaps.

Status

Early stage. As of mid 2026, six rules are implemented and enforced (PYR301, PYR401, PYR402, PYR403, PYR405, PYR406). Eight more are documented but not yet enforced.

• Guideline documentation
• Standalone AST-based checkers (pre-commit local hooks) — PYR301, PYR401, PYR402, PYR403, PYR405, and PYR406 are implemented. PYR201, PYR202, PYR203, PYR204, PYR205, PYR302, PYR404, PYR501, PYR502 are documented but not yet enforced.
• pylint plugin

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 documented so far:

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

1. Browse or open an issue on GitHub Issues
2. Adding a new rule? Follow guidelines/ADDING_A_RULE.md step by step.
3. Run pre-commit run --all-files before pushing.
4. Open a Pull Request.

See CONTRIBUTING.md for full setup and workflow details.

Contact

Maintained by jarl-hoyem. For questions or ideas, open an issue.

License

MIT