Python Style & Quality Gate (Typing • Docstrings • PEP 8/Black • Tests)

Purpose

When writing or modifying Python, apply a “quality gate” aligned to this rule-set:

• •Use type hints consistently (including return types), prefer from __future__ import annotations.
• •Write concise docstrings for public modules/classes/functions (one-line summary + key params/returns/raises) in Google style.
• •Follow PEP 8; Black formatting; keep functions small and cohesive.
• •Provide unit tests that exercise the documented behavior and typed signatures.

When to activate

Activate this skill when:

• •Editing/creating **/*.py, or
• •The user requests: typing, annotations, docstrings, PEP 8, Black, refactor-for-clarity, unit tests, pytest.

Guardrails

• •Minimize blast radius: do NOT reformat or refactor unrelated files unless the user asks.
• •Preserve runtime behavior unless explicitly asked to change it.
• •Prefer repo conventions over personal preference:
  • •If the repo already uses ruff/mypy/pytest/unittest/isort/black settings, follow those.
  • •If no tooling is present, default to Black-compatible formatting and pytest-style tests.

Workflow (agent-operational)

1. •

   Clarify (0–3 questions max) only if needed:

   • •Target Python version? (or infer from pyproject.toml, tox.ini, CI)
   • •Test framework in use (pytest vs unittest)?
   • •Any strict typing expectations (mypy strict, pyright, etc.)?
2. •

   Dynamic context discovery

   • •Locate and follow existing style/tooling:
     • •pyproject.toml, setup.cfg, tox.ini, .ruff.toml, mypy.ini, CI config.
   • •Find canonical patterns in-code (similar modules, existing docstring style, existing test structure).
3. •

   Plan before large edits

   • •For multi-file refactors or public API changes, write a short plan with:
     • •Files to touch
     • •Small incremental steps
     • •Verification steps (commands to run)
4. •

   Implement (incremental)

   • •Add/fix annotations for all params and return types.
     • •Avoid Any unless truly unavoidable; if used, explain why and consider narrower types.
     • •Prefer precise unions, protocols, generics, and typed collections.
   • •Add from __future__ import annotations in new modules; in existing modules, follow repo pattern.
   • •Ensure functions are small and cohesive; if a function is multi-purpose, propose (or perform) a small refactor into smaller units.
5. •

   Docstrings (public surfaces)

   • •Public module/class/function docstrings should be concise:
     • •One-line summary (imperative mood)
     • •Google style sections as needed:
       • •Args / Returns / Raises
   • •Keep docstrings aligned with real behavior and current signature.
6. •

   Tests

   • •Add or update unit tests to cover:
     • •Core behavior
     • •Edge cases implied by types/docs
     • •Error paths (especially documented Raises)
   • •Prefer targeted tests (fast, deterministic). Mirror existing repo testing patterns.
7. •

   Verification

   • •Run the most relevant checks available in the repo (in this order if present):
     • •Formatter/linter (black/ruff)
     • •Type checker (mypy/pyright)
     • •Unit tests (pytest/unittest)
   • •If tools are missing, state what you would run and why.

Output expectations (what “done” looks like)

• •All touched Python functions have explicit param + return annotations.
• •Public API surfaces have up-to-date concise Google-style docstrings.
• •Formatting is Black/PEP8-consistent (or consistent with repo tooling).
• •Tests exist/updated and meaningfully cover the changed behavior.

Common edge cases

• •Legacy codebases without typing:
  • •Add types incrementally; prioritize touched surfaces and high-value boundaries.
• •Dynamic/duck-typed areas:
  • •Prefer Protocol, TypedDict, Mapping[str, Any] (as last resort), or narrow Any usage with justification.
• •Performance-sensitive paths:
  • •Avoid heavy runtime validation; keep typing mostly static.

Examples

Example: function update

Input request: “Add a helper to parse an ISO date string and update callers.”

Expected actions:

• •Create parse_iso_date(value: str) -> datetime.date
• •Add docstring documenting accepted formats and raises
• •Add tests for valid date, invalid date, boundary cases
• •Update callers with correct types

Example: refactor prompt

If a function violates cohesion (multiple responsibilities), propose:

• •Extract 1–3 smaller helpers with tight types
• •Keep behavior identical
• •Add tests around the original public entrypoint