PythonCourt logo

PythonCourt

Python code audit engine powered by AST and Rule
Ensuring AI-generated code meets production-grade quality standards.

pip install pycourt
Install PyCourt into your Python environment.

How PyCourt Works

Instruct the AI to audit its self-generated code with PyCourt
and rectify issues based on the audit report.

Documentation

Production-Grade Quality System

A set of production-grade standards distilled from real-world project iterations,
designed to ensure long-term maintainability and robustness of your system.

AC001
- TheAnyCastLaw -

Prohibits relying on Any, uncontracted dicts and blind typing.cast, to avoid turning core data flows into untyped “duck‑typed” fog that static checks cannot protect.

BC001
- TheBlackCircleLaw -

Prohibits primitive or container types on HTTP/adaptor boundaries, to avoid leaking internal models instead of explicit DTO / contract types at the system edge.

DI001
- TheDepInvLaw -

Prohibits cross‑component imports that bypass core abstractions, to avoid breaking dependency inversion and tightly coupling modules to one another’s implementations.

DT001
- TheDateTimeLaw -

Prohibits direct use of datetime.now() / datetime.utcnow(), to avoid hidden time drift and untestable time‑dependent logic outside a single TimeProvider.

DS001
- TheDocsStringLaw -

Prohibits public functions and classes from lacking clear, non‑trivial docstrings, to avoid opaque APIs whose intent and contract cannot be reviewed or taught.

HC001
- TheHardcodingLaw -

Prohibits hard‑coded business literals and magic numbers outside constant modules, to avoid hiding configuration and cross‑engine contracts in scattered code.

LL001
- TheLineLoopLaw -

Prohibits functions whose length or cyclomatic complexity exceeds agreed thresholds, to avoid procedures that are too large and tangled to reason about safely.

OU001
- TheObjectUsageLaw -

Prohibits using bare object as a type in core code, to avoid “grey fog” values with no contract, where invariants and capabilities cannot be enforced.

PC001
- TheParamClassLaw -

Prohibits treating adjustable business rules as core constants and bypassing the rule provider to directly access rule files, to avoid confusing operational controls with technical constants.

RE001
- TheInitNNoReExpLaw -

Prohibits bloated __init__.py files that contain logic, control flow or export gymnastics, to avoid package facades degenerating into a second hidden implementation module.

SK001
- TheSkillsUsageLaw -

Prohibits hard‑coding Skill IDs or directly reading from assets/skills via file I/O, to avoid coupling business code to physical skill layouts instead of a central SkillId registry and provider.

TC001
- TheTypeCheckingLaw -

Prohibits any use of if TYPE_CHECKING: structures, to avoid hiding circular dependencies behind “type‑only” imports that still entangle modules.

TP001
- TheTestPurityLaw -

Prohibits unit tests that import heavy I/O stacks, smuggle in SQLAlchemy outside whitelists, to avoid slow, brittle and fake‑coverage tests.

UW001
- TheUnitOfWorkLaw -

Prohibits RepositoryFactory usage and commit() / rollback() calls inside repositories, to avoid violating Unit‑of‑Work atomicity and leaking transaction control.

VT001
- TheVectorTriggerLaw -

Prohibits raising vector or materialization events that are not backed by corresponding provider routes, to avoid emitting events that no vector service can actually fulfill at runtime.

Designed Audit Strategies

Provides carefully designed audit strategies for three distinct development scenarios.

Customize Your Courtroom

Define the laws and the trial procedures
Build a complete quality governance system tailored to your project.

Your Project Lawbook

Grant strategic exemptions to respect your architecture.

  • Enable or disable individual laws.
  • Tune thresholds and options per law.
  • Grant strategic exemptions: e.g., exempt the `bootstrap.py` from `DI001` to respect Dependency Inversion.
  • Run pycourt init and then edit it by hand.
# pycourt.yaml
laws:
  ll001:
    enabled: true
    max_function_lines: 50

exemptions:
  DI001:
    files:
      - "src/di/**"

Your Project Quality Sovereignty

Declare the scope of the production code, and accept the review by PyCourt.

  • Map your civilized territory by architectural and dependency.
  • Map scattered components to civilized paths.
  • Use a single source of truth for the coverage threshold.
  • Uncomment a path to start auditing that layer.
  • No comments left means a purified component.
  • Now, PR with confidence.
# pyproject.toml
[tool.pycourt]
# Audit of cross-domain components and modules.
civilized_paths = [
    "src/api",      # civilized
    "src/business", # civilized
    "src/services", # civilized
    "src/infra",    # civilized
    "src/core",     # civilized
    # "tools",      # excluded from this CI run
]

# Single source for the coverage threshold (%).
coverage = 85

Community & Discussion

Stop struggling alone. Start advancing together.

As a beginner learning to code with AI, I was constantly wrestling with the quality.

I built PyCourt—a final method to turn the situation around.

If you have ever had the same doubts, welcome to join the PythonCourt community.

Use & report back

Try to use PyCourt in your project and give feedback on your experience.
I will be very grateful that you have taught me more.

Design & publish

Improve existing laws or design entirely new weapons.

Publish your work so it can benefit others.

Discuss & plan

Propose new laws, weapons, or AI workflows.

Let's discuss how to achieve rapid, high‑quality growth—together.

Ready to team up?

Start a trial, design a weapon, or open a case here:
PythonCourt Organization PyCourt Repository