Python Style Guide

Overview

Scope Boundaries

• Use this skill when the task matches the trigger condition described in

  description

  .
• Do not use this skill when the primary task falls outside this skill's domain.

Trigger Reference

• Use

  references/trigger-matrix.md

  as the canonical trigger and co-activation matrix.
• Resolve skill activation from changed files with

  python3 scripts/resolve_style_guides.py <changed-path>...

  when automation is available.
• Validate trigger matrix consistency with

  python3 scripts/validate_trigger_matrix_sync.py

  .

Quality Gate Reference

• Use

  references/quality-gate-command-matrix.md

  for CI check-only vs local autofix command mapping.

Shared References

• Typing and boundary rules:

  • references/typing-and-boundary-rules.md

Templates And Assets

• Python review checklist:

  • assets/python-review-checklist.md

• Refactor plan template:

  • assets/python-refactor-plan-template.md

Inputs To Gather

• Changed modules and impacted boundaries.
• Typing and data-modeling risk hotspots.
• Error/config/security constraints.
• CI and runtime quality gate expectations.

Deliverables

• Risk-prioritized review findings.
• Refactor plan with validation strategy.
• Merge readiness decision with residual risks.

Workflow

1. Confirm trigger fit and impacted Python artifacts.
2. Plan changes via

   assets/python-refactor-plan-template.md

   .
3. Review with

   assets/python-review-checklist.md

   and project gates.
4. Apply improvements for typing, boundaries, and failure visibility.
5. Execute required checks and publish residual-risk ownership.

Review And Refactor Checklist

Architecture and module boundaries

1. Keep modules cohesive and focused on one responsibility.
2. Isolate side effects (I/O, network, DB) behind clear interfaces.
3. Keep orchestration layers thin and move business rules into domain modules.
4. Avoid circular imports by keeping dependency direction explicit.

Naming and code structure

1. Follow PEP 8 naming conventions (

   snake_case

   ,

   PascalCase

   ,

   UPPER_CASE

   constants).
2. Write small functions with explicit inputs/outputs.
3. Replace magic numbers with named constants including units (

   REQUEST_TIMEOUT_SECONDS

   ).
4. Add short comments only where intent is non-obvious.

Typing and data modeling

1. Add type hints for public functions, methods, and complex locals.
2. Prefer explicit models (

   dataclass

   ,

   TypedDict

   , Pydantic model) over loose dicts.
3. Avoid

   Any

   unless unavoidable and justified inline.
4. Define precise protocols/interfaces for pluggable dependencies.
5. Avoid

   dict[str, Any]

   and

   object

   for domain payloads when structure is known.
6. Convert untyped external input into explicit models once at the boundary, then keep inner layers strongly shaped.
7. Treat repeated

   typing.cast(...)

   usage as a signal to redesign the underlying type contract.

Error handling and control flow

1. Raise specific exception types with actionable messages.
2. Catch exceptions intentionally at boundaries and preserve causal chains.
3. Avoid broad

   except Exception

   unless rethrowing after required cleanup/logging.
4. Do not suppress failures with silent fallback logic by default.

Configuration and environment

1. Parse and validate configuration at startup.
2. Fail startup when required environment variables are missing.
3. Do not hardcode fallback defaults for required environment variables.
4. Keep secrets in secret managers or injected environment, never in code.

Security and compliance

1. Validate untrusted input at boundaries.
2. Use parameterized DB queries; never build SQL with string concatenation.
3. Avoid unsafe deserialization and command execution with unchecked input.
4. Redact secrets and sensitive fields from logs.

Performance and efficiency

1. Measure bottlenecks before optimizing (

   cProfile

   , tracing, metrics).
2. Avoid N+1 data access patterns and repeated expensive computation.
3. Stream large datasets instead of loading everything into memory.
4. Use bounded retries/backoff with named constants.

Testing and verification

1. Add unit tests for core logic and integration tests for boundaries.
2. Cover edge cases: invalid data, timeout, retry exhaustion, concurrency hazards.
3. Add regression tests for every bug fix.
4. Document manual verification when automation cannot cover behavior.

Observability and operations

1. Use structured logs with trace/request IDs.
2. Emit metrics for latency, throughput, and errors.
3. Normalize exception-to-error response mapping at API boundaries.
4. Ensure alertable signals exist for critical failure paths.

CI required quality gates (check-only)

1. Run

   uv run ruff format --check .

   .
2. Run

   uv run ruff check .

   .
3. Run

   uv run mypy .

   (or project type checker equivalent).
4. Run

   uv run pytest -q

   .

Optional autofix commands (local)

1. Run

   uv run ruff format .

   .
2. Run

   uv run ruff check --fix .

   , then re-run checks.

Failure Conditions

• Stop when boundary contracts remain ambiguous after review.
• Stop when required configuration or typing guarantees are missing.
• Escalate when unresolved defects threaten correctness or operability.