python_skill

Overview

This skill provides pragmatic, production-focused guidance for modern Python (3.10+) development. It covers project layout, typing, dataclasses, Pydantic, error handling, decorators, context managers, generators, async/await, file I/O, testing, logging, and dependency management. Use it to write, review, or refactor Python code following current best practices.

How this skill works

The skill inspects Python source and suggests idiomatic patterns: whitespace, type hints, dataclass vs Pydantic decisions, async/sync boundaries, and proper exception handling. It guides project setup (pyproject.toml, src layout, virtual envs), testing with pytest, logging configuration, and safe file operations with pathlib. It also provides snippets for decorators, context managers, generators, and common stdlib utilities.

When to use it

• Creating or reviewing any .py file (non-FastAPI/Agents/n8n contexts)
• Setting up a new Python project or package (pyproject.toml, src/ layout)
• Adding or improving type hints, dataclasses, or Pydantic models
• Writing pytest tests, fixtures, or mocking network calls
• Implementing async code, generators, context managers, or decorators
• Configuring logging, virtual environments, or dependency locking

Best practices

• Prefer pyproject.toml with a build backend (hatchling) and keep src/ layout for editable installs
• Use modern type syntax (| for unions, lowercase generics, TypeAlias, Protocol) to improve clarity and tooling
• Choose dataclasses (slots/frozen) for internal containers and Pydantic for external validation/serialization
• Avoid blocking I/O inside async code; use asyncio.to_thread for sync functions and TaskGroup (3.11+) for concurrency
• Use pathlib for filesystem paths, and json/tomllib for portable parsing; create parent directories with mkdir(parents=True)
• Write focused pytest tests with fixtures and parametrize for coverage; mock external calls with unittest.mock

Example use cases

• Set up a new package skeleton with pyproject.toml, src/mypackage, and tests/ ready for CI
• Add type hints to a legacy module and introduce Protocols for cleaner abstractions
• Replace a mutable config struct with a frozen dataclass and validate inputs in __post_init__
• Write pytest tests for business logic, add fixtures in conftest.py, and mock HTTP calls
• Implement an async fetch_all using asyncio.TaskGroup and ensure non-blocking file reads with to_thread