Python Development

Functional-first, production-first Python 3.14+ with uv, type safety, immutability, and small composable modules.

Activation Triggers

• .py files, pyproject.toml, uv commands, Python packaging
• pip, pip3, poetry, venv, virtualenv, inline script metadata
• Python, typing, asyncio, pytest, mypy, ruff, dataclasses, itertools, functools
• Async I/O, data pipelines, CLI tooling, validation, parsing, test strategy

Workflow

1. MODEL    -> types, invariants, boundaries
2. COMPOSE  -> pure functions, pipelines, small modules
3. VALIDATE -> parse at edges, return errors early
4. TEST     -> pytest, fixtures, async tests
5. HARDEN   -> ruff + format + mypy + regression tests

Core Principles

• Functional core, imperative shell
• Immutability by default; copy-on-write
• Explicit types and error paths
• Small composable units
• Production defaults: logging, config, timeouts, retries
• Prefer uv for running Python, dependency management, environments, scripts, and builds

When to Use

• New or refactored Python modules
• Async I/O, data pipelines, CLI tooling
• Type-heavy APIs, validation, parsing
• Test strategy or flaky tests
• Any request that mentions Python setup, Python dependencies, virtual environments, or script execution

When Not to Use

• Non-Python runtimes
• Browser E2E tests (use Playwright)

uv-first workflow

Use uv instead of raw python, pip, poetry, or python -m venv.

Quick reference

uv run python script.py
uv run pytest
uv run --with requests python script.py
uv add requests pydantic httpx
uv add --dev pytest pytest-asyncio mypy ruff
uv venv
uv run python -m ast path/to/file.py >/dev/null
uv init --script example.py --python 3.12
uv add --script example.py requests rich
uv lock --script example.py

Prefer these replacements

• python script.py -> uv run python script.py
• python -m pytest -> uv run pytest
• pip install x -> uv add x
• python -m venv .venv -> uv venv
• python -m py_compile foo.py -> uv run python -m ast foo.py >/dev/null

Inline script metadata

For standalone scripts, prefer uv inline metadata over ad-hoc setup.

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

Then run:

uv run script.py

Helpful commands:

uv init --script script.py --python 3.12
uv add --script script.py requests rich
uv lock --script script.py

For executable scripts:

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["httpx"]
# ///

Project quick start

uv init my-project && cd my-project
uv add requests pydantic httpx
uv add --dev pytest pytest-asyncio mypy ruff

uv run python script.py
uv run pytest

Quality gates

uv run ruff check src/
uv run ruff format --check src/
uv run mypy src/
uv run pytest

Build backend

Use uv_build for pure Python packages. For extension modules, prefer another backend such as hatchling.

[build-system]
requires = ["uv_build>=0.9.28,<0.10.0"]
build-backend = "uv_build"

Prefer the standard src/ layout unless the repo has a strong reason not to.

Must / Must Not

• MUST: type hints on public APIs; validate inputs at boundaries; prefer pathlib
• MUST: use uv for running Python, adding deps, script metadata, and env setup
• MUST NOT: use raw pip, pip3, poetry, or python -m venv when uv is the intended workflow
• MUST NOT: use mutable default args; bare except; mix sync/async in one call chain

Notes

Core patterns, async examples, and anti-patterns live in reference.md and the cookbooks. Read the relevant cookbook when the task narrows:

• async work -> cookbook/async.md
• functional structure -> cookbook/patterns*.md
• tests -> cookbook/testing*.md
• language features -> cookbook/modern*.md

Research tools

# gh search code for real-world examples
gh search code "asyncio.TaskGroup(" --language=python
gh search code "class.*Protocol):" --language=python
gh search code "async with httpx.AsyncClient(" --language=python

References

• reference.md - Data structures, best practices, idioms, error handling
• patterns.md - Functional patterns
• async.md - Async/await deep dive
• testing.md - pytest patterns & fixtures
• design-patterns.md - Builder, DI, Factory, Strategy, Repository
• modern.md - Python 3.8-3.14 key features