pyrift

pyrift: Silent Python Behaviour Detection

pyrift is a Python library designed to identify silent behavioral differences across various CPython versions and between CPython and PyPy. This tool assists developers in maintaining the integrity of their code by revealing runtime discrepancies that traditional static analysis tools might overlook.

Quick Start with Python API

Integrating pyrift into projects is straightforward. The following code snippet demonstrates how to scan a directory and analyze findings:

import pyrift

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

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

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

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

# Export findings in different 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")

Identifiable Rules

pyrift encompasses rules for both CPython compatibility and PyPy runtime differences:

• CPython Rules (Version Compatibility): Identifies issues that arise from code that may not function as expected across different Python versions. Examples include:

  • CPY001: Dict ordering assumption (Warning for CPython < 3.7)
  • CPY002: Exception.add_note() requires Python 3.11+ (Error for CPython ≤ 3.10)

• PyPy Rules (Runtime Differences): Detects behaviors that differ between PyPy and CPython, such as:

  • PPY001: Relying on __del__ for resource cleanup (Error)
  • PPY002: ctypes usage may silently fail (Warning)

For a complete list of rules, consult the detailed documentation.

Integration with CI/CD

pyrift can be easily integrated into CI pipelines. The following snippet illustrates how to set up pyrift in GitHub Actions:

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

This automatically fails the CI build if errors are detected.

Compatibility with Pre-commit

To ensure code meets standards before committing, pyrift can be added to the pre-commit configuration:

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

Unique Value Proposition

pyrift is positioned as a complementary tool that specifically focuses on silent runtime behavior differences, which is often missed by popular tools such as pylint, mypy, pip-audit, and bandit. This makes it an essential addition to any Python developer's toolkit.

Roadmap and Contributions

The project actively welcomes contributions, particularly in expanding the rule set. Planned enhancements include additional rules for future Python versions and improved integration with development environments.

Project Status

• Current Version: 0.7.0
• Total Rules: 90 (45 for CPython + 45 for PyPy)
• Test Coverage: 392 passing tests
• Dependencies: None
• Supported Python Versions: 3.10+

For those interested in contributing or exploring how to add new rules, please refer to CONTRIBUTING.md.

Author

Developed by Bhuvansh Kataria, a contributor to CPython and author of PyPy toolkit.