How PyCourt Works
Instruct the AI to audit its self-generated code with PyCourt
and rectify issues based on the audit report.
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.
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.
Prohibits primitive or container types on HTTP/adaptor boundaries, to avoid leaking internal models instead of explicit DTO / contract types at the system edge.
Prohibits cross‑component imports that bypass core abstractions, to avoid breaking dependency inversion and tightly coupling modules to one another’s implementations.
Prohibits direct use of datetime.now() / datetime.utcnow(), to avoid hidden time drift and untestable time‑dependent logic outside a single TimeProvider.
Prohibits public functions and classes from lacking clear, non‑trivial docstrings, to avoid opaque APIs whose intent and contract cannot be reviewed or taught.
Prohibits hard‑coded business literals and magic numbers outside constant modules, to avoid hiding configuration and cross‑engine contracts in scattered code.
Prohibits functions whose length or cyclomatic complexity exceeds agreed thresholds, to avoid procedures that are too large and tangled to reason about safely.
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.
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.
Prohibits bloated __init__.py files that contain logic, control flow or export gymnastics, to avoid package facades degenerating into a second hidden implementation module.
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.
Prohibits any use of if TYPE_CHECKING: structures, to avoid hiding circular dependencies behind “type‑only” imports that still entangle modules.
Prohibits unit tests that import heavy I/O stacks, smuggle in SQLAlchemy outside whitelists, to avoid slow, brittle and fake‑coverage tests.
Prohibits RepositoryFactory usage and commit() / rollback() calls inside repositories, to avoid violating Unit‑of‑Work atomicity and leaking transaction control.
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.
Immediate purification, zero debt.
- Performs static audit on a single '.py' file.
- Customize which laws to apply and in what order.
- Co‑runs with Pyright, Mypy, Bandit and Ruff as needed.
- Discover violations and provide explanations and suggested fixes
Batch purification, no collateral damage.
- Performs static audits on all files within a folder.
- Discovers associated test code, performs a static audit on it, and runs the unit tests.
- Investigation mode to capture all violations and plan remediation.
Cross‑domain integrity, one‑click acceptance.
- Performs integrated audit for a logical component across directories.
- Invokes Saber to perform static audits on audit objectives and test code.
- Drives unit and integration tests across the whole project scope.
- Start a smooth journey in PR and CI/CD.
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 initand 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