pycodereview 2.0.0

Static checks for common Python code risks and hygiene issues.

pycodereview

Static checks for common Python code risks and hygiene issues.
Runs on a single file and outputs concise, review-ready reports in CSV or JSON.

---

Why pycodereview?

Most static analysis tools (like pylint, flake8, or ruff) are great at style compliance and large rule catalogs.

pycodereview is different: it’s built to support human code review with clear, impact-based findings.

It aims to:

• Group findings by impact (Correctness, Security, Robustness, etc.) instead of cryptic rule codes.
• Bridge readability and auditability (messages explain why it matters).
• Stay lightweight and dependency-free (built on Python’s ast / tokenize).
• Highlight risky patterns, not just style issues (mutable defaults, unsafe deserialization, misuse of assert, etc.).
• Produce reports you can share in CSV/JSON for CI gates, audits, and review discussions.

---

Quick Start

Install:

pip install pycodereview

Run analysis on a file:

pycodereview path/to/file.py

Write a CSV report:

pycodereview path/to/file.py --out review_report.csv

Generate JSON output:

pycodereview path/to/file.py --json-output review.json

Example JSON output:

[
  {
    "file": ".\\tests\\data\\sample_cases.py",
    "category": "Correctness",
    "priority": "HIGH",
    "impacted_lines": "65",
    "potential_impact": "Shared mutable state across calls; surprising behavior.",
    "description": "sample_cases.py: Mutable default in function \"bad_defaults_a\"."
  },
  {
    "file": ".\\tests\\data\\sample_cases.py",
    "category": "Correctness",
    "priority": "HIGH",
    "impacted_lines": "70",
    "potential_impact": "Shared mutable state across calls; surprising behavior.",
    "description": "sample_cases.py: Mutable default in function \"bad_defaults_b\"."
  }
]

---

What it checks

pycodereview focuses on review-relevant risks that commonly slip into production.

Error Handling

• Catch-alls and empty except
• Improper exception re-raise losing traceback/context

Correctness

• Mutable default args
• Misuse of assert for runtime validation
• Identity vs equality pitfalls
• Undefined variables / shadowing hazards
• Return annotation mismatches and suspicious flows

Security

• eval / exec
• Unsafe subprocess or os.system
• Insecure YAML / Pickle loads
• Weak hashes (md5, sha1)
• Hardcoded secrets/tokens (basic signals)
• Unsafe HTTP patterns (verify=False, etc.)

Concurrency (lightweight signals)

• Import-time multiprocessing hazards
• Misuse patterns around tasks/lifecycle
• Blocking calls inside async functions (e.g. time.sleep)

Resource Management

• Missing context managers (with open(...))
• File mode mismatches and missing encoding
• Unsafe tempfile patterns (e.g. mktemp())

Robustness

• Unguarded dict/key access patterns
• Common len/type footguns
• Fragile reliance on ordering assumptions

Maintainability & Hygiene

• Wildcard imports
• Unused imports/variables
• Missing docstrings for public API (where applicable)
• Debug prints and noisy markers
• Non-Pythonic loops / suspicious constructs
• Magic literals (heuristic)

Process

• TODO/FIXME markers (review surfacing)

---

Output Formats

CSV

Columns:

1. Category
2. Priority
3. Impacted lines
4. Potential impact
5. Description

JSON

Each finding is a JSON object with keys:

• file
• category
• priority
• impacted_lines
• potential_impact
• description

---

CLI

pycodereview FILE [options]

Options:
  --out OUT              Output CSV path. Default: review_report.csv
  --json-output PATH     Write JSON-formatted report.
  --min-priority {LOW,MEDIUM,HIGH}
                         Only report issues at or above this priority.
  --merge-issues         Merge identical issues across multiple lines.
  --max-lines N          Cap the number of lines listed per issue (default: 1200)
  --version              Show version and exit
  -h, --help             Show help message and exit

---

Learn more about CRSS-Python (v1.0.0)

CRSS-Python is a safety and compliance standard that pycodereview progressively supports.

• CRSS-Python Overview & Repository Map (v1.0.0)
  https://github.com/sofiand-png/pycodereview/tree/v2.0.0/CRSS/0-Overview/crss_python_overview_landing.md

CRSS-Python (Certifiable Reliability Safety Standard - Python) is an original safety and reliability standard for Python, authored by Sofian Daghsen. It defines two profiles:

• CRSS-Core - a pragmatic profile for general Python code.
• CRSS-Strict - a constrained, analyzable subset for critical units

CRSS-Python makes Python suitable for:

• Automotive safety systems
• Industrial control
• Medical devices
• Critical monitoring systems
• High-assurance automation
• Mission-critical supervisory logic

---

Relationship to CRSS-Python

pycodereview is the reference static-analysis engine for the CRSS-Python Standard - a safety-oriented subset of Python inspired by MISRA-style discipline and certification expectations.

What you can do today (no CRSS required)

You can use pycodereview as a lightweight review tool:

pycodereview file.py

No config required. It produces impact-based findings you can use in reviews and CI.

What CRSS adds (standard + structured compliance)

CRSS introduces:

• Stable rule IDs (e.g., CRSS-3.1.5, CRSS-6.2.1, CRSS-9.1.4)
• Two profiles:
  • Core: pragmatic baseline for most Python code
  • Strict: analyzable subset for @critical / high-integrity logic
• Deviation handling, compliance reporting, and evidence structure
• Import / inheritance policies and certification-facing artifacts
• Certified Deployment/Packaging
• Compliance Process/ External Assessment Process

Where the CRSS documents live in this repo

(Repository paths)

• CRSS/1-Specifications/Profiles/crss_python_core_spec.md
• CRSS/1-Specifications/Profiles/crss_python_strict_spec.md
• CRSS/1-Specifications/Master/crss_python_standard_safety_master.md
• CRSS/0-Overview/crss_python_overview_landing.md

CRSS and pycodereview are versioned separately so projects can adopt CRSS progressively.

---

Roadmap: toward full CRSS-aware enforcement

Planned additions (without breaking the current default experience):

1. Profile-aware analysis

   pycodereview myfile.py --profile core
   pycodereview myfile.py --profile strict
   

   • default remains today’s lightweight behavior.

2. Rule-ID mapping

   • Findings carry CRSS IDs where applicable.

3. Project configuration (crss.toml)

   • Declared profiles, critical zones, Python version range, deviation policy, requirements mapping.

4. Safety-style reports

   • Guideline compliance summaries, deviation logs, requirement traceability outputs.

5. Advanced verification (planned / exploratory)

   • MC/DC reporting for critical logic (where required)
   • Path exploration / bounded analysis experiments

---

Local development

pip install -r requirements-dev.txt
pytest --cov=src/pycodereview --cov-report=term --cov-report=html

---

Limitations

• Not a replacement for full linters/type-checkers (ruff, flake8, mypy).
• Some security checks are conservative; false positives are possible.
• Reports only; no auto-fixes.

---

Contributing

PRs welcome. Please:

• add unit tests for new rules,
• keep messages concise and actionable,
• document new options in the README,
• run formatting/linting before committing.

---

Licensing

pycodereview software

The pycodereview software (source code, binaries, and package artifacts) is licensed under the MIT License (see LICENSE).

CRSS-Python standard text (specifications)

The CRSS-Python specification documents (Core, Strict, and all specifications) are licensed under the Creative Commons Attribution-NonCommercial–NoDerivatives 4.0 International License (CC BY-NC-ND 4.0).

You are free to:

• Share: copy and redistribute the material in any medium or format

Under the following terms:

• Attribution: You must give appropriate credit.
• NonCommercial: You may not use the material for commercial purposes.
• NoDerivatives: You may not distribute modified versions.

This license applies only to the standard text located under:

• CRSS/

(Repository note: in this repository layout, CRSS documents live under CRSS/ and are distributed with the same stated terms in their headers.)