python

Python

Purpose

Write production Python that is type-safe, async-first, and testable. This skill sets a single quality bar — annotated, linted, tested — and applies it consistently to new code and to code being modernized.

When to Use

• Writing new Python modules, packages, or services.
• Adding type coverage to an untyped or partially typed codebase.
• Converting blocking I/O to asyncio, or debugging async behavior.
• Standing up a pytest suite, fixtures, or parametrized tests.
• Modernizing Python 2-era or pre-3.10 idioms.

Capabilities

• Full type annotation, including generics, Protocol, TypedDict, and ParamSpec.
• Async design: task groups, timeouts, cancellation, structured concurrency.
• Data modeling with dataclasses, enum, and Pydantic when validation is needed.
• Test authoring: fixtures, factories, mocking, property-based tests via Hypothesis.
• Tooling configuration: pyproject.toml, ruff, mypy, uv or Poetry.
• Profiling and hot-path optimization.

Inputs

• Source files or a package path.
• Target Python version (default: 3.12).
• Existing tooling config, if any.
• Runtime constraints: sync vs async, framework, deployment target.

Outputs

• Type-annotated source that passes mypy --strict.
• A pytest suite with meaningful assertions, not coverage padding.
• A pyproject.toml section configuring ruff and mypy.
• A short summary of behavioral changes when refactoring.

Workflow

1. Survey — Read the module and its imports. Identify the runtime model (sync, async, threaded) and existing conventions. Do not fight established conventions without a reason.
2. Model the data — Define dataclasses, enums, and protocols before writing logic. Type the boundaries first.
3. Implement — Write the smallest correct version. Prefer standard library over dependencies.
4. Test — Cover the contract and the failure modes, not the implementation details.
5. Gate — Run ruff check --fix, ruff format, mypy --strict, pytest. Fix each failure and re-run until all four are clean.