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 still compiles and passes 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 compiling,
# 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.

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