python-pro

SKILL.md

Python Pro

Modern Python 3.11+ specialist focused on type-safe, async-first, production-ready code.

When to Use This Skill

Writing type-safe Python with complete type coverage

Implementing async/await patterns for I/O operations

Setting up pytest test suites with fixtures and mocking

Creating Pythonic code with comprehensions, generators, context managers

Building packages with Poetry and proper project structure

Performance optimization and profiling

Core Workflow

Analyze codebase — Review structure, dependencies, type coverage, test suite

Design interfaces — Define protocols, dataclasses, type aliases

Implement — Write Pythonic code with full type hints and error handling

Test — Create comprehensive pytest suite with >90% coverage

Validate — Run mypy --strict, black, ruff

If mypy fails: fix type errors reported and re-run before proceeding

If tests fail: debug assertions, update fixtures, and iterate until green

If ruff/black reports issues: apply auto-fixes, then re-validate

Reference Guide

Load detailed guidance based on context:

Topic
Reference
Load When

Type System
references/type-system.md
Type hints, mypy, generics, Protocol

Async Patterns
references/async-patterns.md
async/await, asyncio, task groups

Standard Library
references/standard-library.md
pathlib, dataclasses, functools, itertools

Testing
references/testing.md
pytest, fixtures, mocking, parametrize

Packaging
references/packaging.md
poetry, pip, pyproject.toml, distribution

Constraints

MUST DO

Type hints for all function signatures and class attributes

PEP 8 compliance with black formatting

Comprehensive docstrings (Google style)

Test coverage exceeding 90% with pytest

Use X | None instead of Optional[X] (Python 3.10+)

Async/await for I/O-bound operations

Dataclasses over manual init methods

Context managers for resource handling

MUST NOT DO

Skip type annotations on public APIs

Use mutable default arguments

Mix sync and async code improperly

Ignore mypy errors in strict mode

Use bare except clauses

Hardcode secrets or configuration

Use deprecated stdlib modules (use pathlib not os.path)

Code Examples

Type-annotated function with error handling

from pathlib import Path

def read_config(path: Path) -> dict[str, str]:
    """Read configuration from a file.

    Args:
        path: Path to the configuration file.

    Returns:
        Parsed key-value configuration entries.

    Raises:
        FileNotFoundError: If the config file does not exist.
        ValueError: If a line cannot be parsed.
    """
    config: dict[str, str] = {}
    with path.open() as f:
        for line in f:
            key, _, value = line.partition("=")
            if not key.strip():
                raise ValueError(f"Invalid config line: {line!r}")
            config[key.strip()] = value.strip()
    return config

Dataclass with validation

from dataclasses import dataclass, field

@dataclass
class AppConfig:
    host: str
    port: int
    debug: bool = False
    allowed_origins: list[str] = field(default_factory=list)

    def __post_init__(self) -> None:
        if not (1 <= self.port <= 65535):
            raise ValueError(f"Invalid port: {self.port}")

Async pattern

import asyncio
import httpx

async def fetch_all(urls: list[str]) -> list[bytes]:
    """Fetch multiple URLs concurrently."""
    async with httpx.AsyncClient() as client:
        tasks = [client.get(url) for url in urls]
        responses = await asyncio.gather(*tasks)
        return [r.content for r in responses]

pytest fixture and parametrize

import pytest
from pathlib import Path

@pytest.fixture
def config_file(tmp_path: Path) -> Path:
    cfg = tmp_path / "config.txt"
    cfg.write_text("host=localhost\nport=8080\n")
    return cfg

@pytest.mark.parametrize("port,valid", [(8080, True), (0, False), (99999, False)])
def test_app_config_port_validation(port: int, valid: bool) -> None:
    if valid:
        AppConfig(host="localhost", port=port)
    else:
        with pytest.raises(ValueError):
            AppConfig(host="localhost", port=port)

mypy strict configuration (pyproject.toml)

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

Clean mypy --strict output looks like:

Success: no issues found in 12 source files

Any reported error (e.g., error: Function is missing a return type annotation) must be resolved before the implementation is considered complete.

Output Templates

When implementing Python features, provide:

Module file with complete type hints

Test file with pytest fixtures

Type checking confirmation (mypy --strict passes)

Brief explanation of Pythonic patterns used

Knowledge Reference

Python 3.11+, typing module, mypy, pytest, black, ruff, dataclasses, async/await, asyncio, pathlib, functools, itertools, Poetry, Pydantic, contextlib, collections.abc, Protocol

Documentation