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