Python

Python

Policy-level Python guidance. Load one focused ref for deep detail; keep this file as router + defaults.

Reference Map

Assets

• assets/project/pyproject.toml
• assets/project/src/myapp/main.py
• assets/project/src/myapp/settings.py
• assets/project/tests/test_main.py
• assets/project/scripts/report.py

Onboarding

Detect:

ls pyproject.toml 2>/dev/null

Before edit:

1. verify tools
2. find validation entrypoints
3. inspect layout/config/tests
4. check momentum: git log --oneline -10

Validation discovery order:

1. task aliases in pyproject.toml
2. direct uv run ...
3. README/scripts
4. CI config

Default Stack

• Python 3.12+
• uv
• ruff
• ty
• pyright
• pytest
• rumdl
• taskipy
• pre-commit
• bandit
• rtk

Validation

uv run ruff format --check .
uv run ruff check .
uv run rumdl check .
uv run ty check
uv run pyright
uv run pytest -v

Prefer task aliases when repo defines them:

uv run task lint
uv run task fmt
uv run task type
uv run task test
uv run task test-cov
uv run task sec

Verify tools:

uv --version
python --version
uv run ruff --version
uv run ty --version
uv run pyright --version
uv run pytest --version
uv run rumdl --version
uv run task --version
uv run pre-commit --version
uv run bandit --version

Install deps:

uv sync

Core Defaults

• use uv, uv run, uv add; avoid direct pip
• format with ruff
• prefer pathlib, f-strings, absolute imports
• type public APIs; use Protocol at boundaries; contain Any
• externalize config/secrets with typed settings loaded at startup
• validate external input at boundaries; convert raw payloads early
• keep IO at edges; avoid leaking ORM/transport types
• prefer composition/focused modules over clever abstractions
• default sync unless real concurrent I/O pressure exists
• keep async path async end-to-end when used
• centralize retries, timeouts, cleanup
• make background jobs idempotent and explicit about state/ownership
• keep observability structured and outside core business logic
• test behavior and boundaries; avoid framework-heavy tests when simple tests suffice
• optimize only after measuring bottleneck

Build-Fix

Order:

1. format
2. lint
3. markdown
4. typing
5. tests

After each fix, rerun failing check. Stop/report if fix needs architecture change. Run uv run task sec for explicit security review; do not treat it as part of the default quick check unless the repo opts in.

Common fixes:

Debug

1. reproduce exactly
2. record env
3. read traceback bottom-up
4. inspect git log --oneline -10 and git diff
5. isolate boundary
6. use git bisect if regression likely
7. confirm fix with failing test/command
8. remove temp debug/breakpoints

Rules: do not guess first; fix root cause; one hypothesis at time; do not silence with broad try/except; do not change tests to match bug.

FastAPI Cues

• use Annotated for Path, Query, Header, Depends
• reusable dependency aliases only when repeated signatures simplify
• no ellipsis ... for required FastAPI/Pydantic fields
• explicit return type or response_model
• router-level prefix, tags, dependencies
• default def if internals may block
• no blocking code inside async handlers
• prefer HTTPX over Requests
• no deprecated ORJSONResponse/UJSONResponse performance crutch
• no RootModel when normal typed structure is enough

Review Focus

• correctness: edge cases, error paths, races
• security: boundary validation, secrets, injection, auth
• performance: blocking async, N+1, unbounded loops
• maintainability: SRP, dead code, magic values, noisy comments
• conventions: naming, style, project patterns

Skip style already enforced by tools.

Refactoring

• preserve behavior
• no hidden feature work
• do not rewrite stable code just because old
• reduce complexity only with clear maintenance gain
• one logical change at time

Workflow Cues

• API contract shape -> pair design
• architecture/boundaries -> pair arch
• test-first or failure diagnosis -> pair quality