Quick start - Python API

import pyrift

# Scan a directory
result = pyrift.scan("./src")

print(result)
# ScanResult(files=23, errors=2, warnings=1, score=77)

# Iterate findings
for finding in result.findings:
    print(finding)

# Filter by severity
for error in result.errors:
    print(f"{error.file}:{error.line} - {error.title}")

# Export formats
json_output     = pyrift.to_json(result)
markdown_output = pyrift.to_markdown(result)
text_output     = pyrift.to_text(result)

# Scan a single file
findings = pyrift.scan_file("./src/utils.py")

---

Rules

CPython rules - version compatibility

PyPy rules - runtime differences

Cross-runtime rules

Full rule documentation: docs/rules.md

---

Use in CI

Add pyrift to your GitHub Actions workflow:

- name: Run pyrift
  run: |
    pip install pyrift
    pyrift scan . --format json --output pyrift-report.json
    pyrift scan .

Exit code is 1 when errors are found - fails the CI build automatically. Use --exit-zero to report without failing.

---

Use with pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/BHUVANSH855/pyrift
    rev: v0.8.0
    hooks:
      - id: pyrift

---

Why pyrift?

PyRift focuses on compatibility and behavioural differences that conventional linters and type checkers generally do not model. It complements — not replaces — the tools above.

---

Git-aware scanning

For maintainer and CI workflows, PyRift can scan only Python files changed relative to a Git revision (including staged and untracked changes):

pyrift scan . --changed-only
pyrift scan . --changed-only --base origin/main

---

Features

Dynamic import detection

Some compatibility issues hide behind imports resolved at runtime rather than through import statements. PyRift detects these too:

• importlib.import_module("removed_module")
• __import__("removed_module")

Only statically-resolvable module names are flagged; names computed at runtime from a variable are deliberately left alone to avoid false positives.

Version-guard awareness

PyRift understands sys.version_info guards. A module import protected by a sys.version_info >= (3, N) check that already covers the required version is not reported, because the guarded code never runs on an affected interpreter.

Confidence and evidence

Every finding carries a confidence (high / medium / low) and an evidence_type (official_docs, runtime_probe, deprecation_warn, pep, observed, inferred). These are assigned from a central reviewed table (pyrift/rule_metadata.py); unreviewed rules conservatively default to low / inferred rather than over-claiming certainty.

Multi-name import deduplication

from tomllib import load, loads produces a single finding, not one per imported name, so reports stay readable and stable.

Target-aware filtering

When pyproject.toml declares requires-python, PyRift drops CPython findings that cannot affect the project's supported version range. You can also override with --python-min / --python-max.

Rule-robustness guarantee

Every rule is exercised against a broad suite of exotic-but-valid AST constructs via benchmark/fuzz_harness.py to guarantee no rule ever crashes on valid Python — regardless of finding outcome.

---

Roadmap

Planned for upcoming versions - contributions welcome:

• CPY064+ - next CPython compatibility rules (open for contributions)
• PPY048+ - next PyPy runtime difference rules (open for contributions)
• Pre-commit hook native support
• VS Code extension
• GitHub Action marketplace listing

See CONTRIBUTING.md to add a rule yourself. New rule IDs are assigned after reviewing the existing rule inventory to avoid collisions and duplicate coverage.

---

Contributing

Contributions are very welcome - especially new rules for behaviour differences you have personally encountered.

See CONTRIBUTING.md for the full guide.

---

Project status

• Version: 0.8.0
• Rules: 101 total (57 CPython + 43 PyPy + 1 cross-runtime)
• Tests: 1117 passing
• Dependencies: zero
• Python: 3.10+

---

Rule Trustworthiness

Every finding carries a confidence level and evidence type. Rules are classified into three tiers:

Rule evidence and intentionality are documented in docs/behavior-evidence.md.

Unreviewed rules (no entry in pyrift/rule_metadata.py) default to low confidence, inferred evidence, and inferred intent basis. See the Confidence and evidence feature description for details.

---

Known Limitations

• Static analysis cannot verify runtime behaviour. PyRift inspects ASTs, not executed code. Some findings may be false positives if the flagged code is never reached or is guarded at runtime.
• Some rules are heuristics, not proofs. A rule may flag code that happens to be compatible in practice. Always review findings in context.
• PyPy rules may become outdated as PyPy evolves. Report false positives so rules can be updated or deprecated.
• Free-threading rules are experimental. The CPython 3.13+ free-threading (no-GIL) build is new and its semantics are still stabilising. Rules for free-threaded code may change.
• Version ranges are conservative. Affected-version bounds are based on documented changes; edge cases or backported fixes may alter the actual impact.

---

Author

Built by Bhuvansh Kataria - CPython contributor and PyPy toolkit author.

---

License

MIT - see LICENSE

Security

Found a security issue in PyRift itself? Please follow our Security Policy and report it privately rather than opening a public issue.