Python Best Practices

Worked code examples for every section live in reference.md (sibling file). This SKILL.md carries the rules; open reference.md when you need a concrete snippet to copy.

Type Hints (3.12+ Syntax)

• Always type function signatures. Use built-in generics (list[str], dict[str, int]) — no typing.List/typing.Dict.
• Use X | None union syntax (3.10+) instead of Optional[X].
• Use the type alias and def f[T](...) type-parameter syntax (3.12+) for generics.
• Use TypedDict for structured dicts.
• Run mypy --strict or pyright in CI. Use # type: ignore sparingly and only with a justification.
• Examples: see reference.md § Type Hints.

Dataclasses vs Pydantic

• Dataclasses for domain models and internal structs (no validation needed). Use frozen=True for immutable value objects, slots=True for memory efficiency, field(default_factory=...) for mutable defaults.
• Pydantic for API boundaries, config files, and external data parsing (validation required). Use Field(...) constraints and @field_validator for custom checks; set model_config = {"strict": True}.
• Rule of thumb: internal/trusted data → dataclass; external/untrusted input → Pydantic.
• Examples: see reference.md § Dataclasses vs Pydantic.

Async Patterns

• Use httpx instead of requests for async HTTP.
• Use asyncio.gather for concurrent tasks; asyncio.Semaphore to bound concurrency / rate-limit.
• Never call blocking I/O in async functions — wrap legacy blocking code in asyncio.to_thread.
• Use async with for resource management (connections, sessions, clients).
• Examples: see reference.md § Async Patterns.

Project Structure

• Use a src/ layout (src/my_project/...) to prevent accidental imports from the project root.
• Mirror packages under tests/ with a conftest.py for shared fixtures.
• Full tree: see reference.md § Project Structure.

pyproject.toml

• Put all tool configuration in pyproject.toml (build, deps, ruff, mypy, pytest).
• Use Ruff instead of flake8 + isort + black — one tool, 10-100x faster. Recommended lint select: ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"].
• Set requires-python = ">=3.12", [tool.mypy] strict = true, and asyncio_mode = "auto" for pytest.
• Full template: see reference.md § pyproject.toml.

Virtual Environments

• Always use a virtual environment. Never install packages globally.
• Prefer uv (uv venv + uv pip install -e ".[dev]") for speed; standard venv works too.
• Pin exact versions in a lockfile (uv.lock or a pip freeze-generated requirements.txt).
• Commands: see reference.md § Virtual Environments.

Testing with pytest

• Put shared fixtures in conftest.py. Use pytest.mark.parametrize for test variations and the tmp_path fixture for filesystem tests.
• Name tests by behavior (test_create_user_rejects_duplicate_email), assert on outcomes, and assert error cases with pytest.raises.
• Mock async dependencies with AsyncMock(spec=...); assert call args.
• Examples: see reference.md § Testing with pytest.

Pythonic Idioms

• Prefer unpacking (first, *rest = items), comprehensions over map/filter, and context managers for cleanup.
• Use the walrus operator (:=) for assign-and-test, and structural pattern matching (match/case, 3.10+) for dispatch.
• Examples: see reference.md § Pythonic Idioms.

Error Handling

• Never use bare except:. Catch the most specific exception possible.
• Define a custom exception hierarchy for the application (e.g. AppError → NotFoundError).
• Use logger.exception() to capture tracebacks when handling unexpected errors.
• Examples: see reference.md § Error Handling.

Checklist

• Every function signature is typed; mypy --strict/pyright clean.
• Built-in generics + X | None unions; no typing.List/Optional.
• Dataclasses for internal models, Pydantic at external boundaries.
• Async uses httpx, gather, bounded concurrency; no blocking I/O in coroutines.
• src/ layout; all config in pyproject.toml; Ruff configured.
• Virtual env in use; dependencies pinned in a lockfile.
• Tests assert behavior + error cases; fixtures in conftest.py.
• No bare except; custom exception hierarchy; logger.exception() for tracebacks.