python-style

What this skill does

# 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