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
Maintained by @jeffallan, Principal Consultant at Synergetic Solutions
Documentation
1---2name: python-pro3description: Use when building Python 3.11+ applications requiring type safety, async programming, or robust error handling. Generates type-annotated Python code, configures mypy in strict mode, writes pytest test suites with fixtures and mocking, and validates code with black and ruff. Invoke for type hints, async/await patterns, dataclasses, dependency injection, logging configuration, and structured error handling.4license: MIT5metadata:6 source: https://skillmd.com/skills/tuyv/python-pro7 author: https://github.com/Jeffallan8 company: https://synergetic.solutions9 version: "1.1.0"10 domain: language11 triggers: Python development, type hints, async Python, pytest, mypy, dataclasses, Python best practices, Pythonic code12 role: specialist13 scope: implementation14 output-format: code15 related-skills: fastapi-expert, devops-engineer16---1718# Python Pro1920Modern Python 3.11+ specialist focused on type-safe, async-first, production-ready code.2122## When to Use This Skill2324- Writing type-safe Python with complete type coverage25- Implementing async/await patterns for I/O operations26- Setting up pytest test suites with fixtures and mocking27- Creating Pythonic code with comprehensions, generators, context managers28- Building packages with Poetry and proper project structure29- Performance optimization and profiling3031## Core Workflow32331. **Analyze codebase** — Review structure, dependencies, type coverage, test suite342. **Design interfaces** — Define protocols, dataclasses, type aliases353. **Implement** — Write Pythonic code with full type hints and error handling364. **Test** — Create comprehensive pytest suite with >90% coverage375. **Validate** — Run `mypy --strict`, `black`, `ruff`38 - If mypy fails: fix type errors reported and re-run before proceeding39 - If tests fail: debug assertions, update fixtures, and iterate until green40 - If ruff/black reports issues: apply auto-fixes, then re-validate4142## Reference Guide4344Load detailed guidance based on context:4546| Topic | Reference | Load When |47|-------|-----------|-----------|48| Type System | `references/type-system.md` | Type hints, mypy, generics, Protocol |49| Async Patterns | `references/async-patterns.md` | async/await, asyncio, task groups |50| Standard Library | `references/standard-library.md` | pathlib, dataclasses, functools, itertools |51| Testing | `references/testing.md` | pytest, fixtures, mocking, parametrize |52| Packaging | `references/packaging.md` | poetry, pip, pyproject.toml, distribution |5354## Constraints5556### MUST DO57- Type hints for all function signatures and class attributes58- PEP 8 compliance with black formatting59- Comprehensive docstrings (Google style)60- Test coverage exceeding 90% with pytest61- Use `X | None` instead of `Optional[X]` (Python 3.10+)62- Async/await for I/O-bound operations63- Dataclasses over manual __init__ methods64- Context managers for resource handling6566### MUST NOT DO67- Skip type annotations on public APIs68- Use mutable default arguments69- Mix sync and async code improperly70- Ignore mypy errors in strict mode71- Use bare except clauses72- Hardcode secrets or configuration73- Use deprecated stdlib modules (use pathlib not os.path)7475## Code Examples7677### Type-annotated function with error handling78```python79from pathlib import Path8081def read_config(path: Path) -> dict[str, str]:82 """Read configuration from a file.8384 Args:85 path: Path to the configuration file.8687 Returns:88 Parsed key-value configuration entries.8990 Raises:91 FileNotFoundError: If the config file does not exist.92 ValueError: If a line cannot be parsed.93 """94 config: dict[str, str] = {}95 with path.open() as f:96 for line in f:97 key, _, value = line.partition("=")98 if not key.strip():99 raise ValueError(f"Invalid config line: {line!r}")100 config[key.strip()] = value.strip()101 return config102```103104### Dataclass with validation105```python106from dataclasses import dataclass, field107108@dataclass109class AppConfig:110 host: str111 port: int112 debug: bool = False113 allowed_origins: list[str] = field(default_factory=list)114115 def __post_init__(self) -> None:116 if not (1 <= self.port <= 65535):117 raise ValueError(f"Invalid port: {self.port}")118```119120### Async pattern121```python122import asyncio123import httpx124125async def fetch_all(urls: list[str]) -> list[bytes]:126 """Fetch multiple URLs concurrently."""127 async with httpx.AsyncClient() as client:128 tasks = [client.get(url) for url in urls]129 responses = await asyncio.gather(*tasks)130 return [r.content for r in responses]131```132133### pytest fixture and parametrize134```python135import pytest136from pathlib import Path137138@pytest.fixture139def config_file(tmp_path: Path) -> Path:140 cfg = tmp_path / "config.txt"141 cfg.write_text("host=localhost\nport=8080\n")142 return cfg143144@pytest.mark.parametrize("port,valid", [(8080, True), (0, False), (99999, False)])145def test_app_config_port_validation(port: int, valid: bool) -> None:146 if valid:147 AppConfig(host="localhost", port=port)148 else:149 with pytest.raises(ValueError):150 AppConfig(host="localhost", port=port)151```152153### mypy strict configuration (pyproject.toml)154```toml155[tool.mypy]156python_version = "3.11"157strict = true158warn_return_any = true159warn_unused_configs = true160disallow_untyped_defs = true161```162163Clean `mypy --strict` output looks like:164```165Success: no issues found in 12 source files166```167Any reported error (e.g., `error: Function is missing a return type annotation`) must be resolved before the implementation is considered complete.168169## Output Templates170171When implementing Python features, provide:1721. Module file with complete type hints1732. Test file with pytest fixtures1743. Type checking confirmation (mypy --strict passes)1754. Brief explanation of Pythonic patterns used176177## Knowledge Reference178179Python 3.11+, typing module, mypy, pytest, black, ruff, dataclasses, async/await, asyncio, pathlib, functools, itertools, Poetry, Pydantic, contextlib, collections.abc, Protocol180181Maintained by [@jeffallan](https://github.com/jeffallan), Principal Consultant at [Synergetic Solutions](https://synergetic.solutions)182183[Documentation](https://jeffallan.github.io/claude-skills/skills/language/python-pro/)