ABOUTME: Complete Python development with uv package manager, quality tools, and Docker

ABOUTME: Modern workflow with uv, ruff, ty, pytest, Pydantic, and containerization

Python Development

Quick Reference

uv init myproject && cd myproject
uv add requests pydantic httpx
uv add --dev pytest ruff
uv sync --locked
uv run python main.py
uv run ruff check . && uv run ruff format --check . && uvx ty check && uv run pytest

See also: _AST_GREP.md, _PATTERNS.md, source-control

Version (determine, don't assume)

See ../_LANG_COMMON.md. Fetch the truth:

python3 --version                                                      # local interpreter
cat .python-version 2>/dev/null                                        # pin file (if present)
grep -E '^python' pyproject.toml 2>/dev/null                           # project manifest
curl -s https://endoflife.date/api/python.json | jq -r '.[0].latest'   # latest upstream stable

Pre-Commit Verification (MANDATORY)

make check && make test-e2e must pass (enforced by the pre-commit-gate hook; see ../_LANG_COMMON.md). What make check expands to for Python:

uv run ruff check .
uv run ruff format --check .
uvx ty check
uv run pytest --cov=myproject

Package Management (uv)

Use uv for all dependency management and execution, not pip, poetry or pipenv: universal lockfile, fast resolver.

pyproject.toml

[project]
name = "myproject"
requires-python = ">=<project floor>"   # from .python-version / endoflife.date, do not hardcode from memory
dependencies = ["httpx", "pydantic"]     # `uv add` writes the resolved lower bounds

[dependency-groups]
dev = ["pytest", "ruff"]

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

Code Quality

Ruff config:

[tool.ruff]
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM", "TCH", "RUF", "PERF"]

Testing: pytest with fixtures, AAA pattern, parametrize. Coverage via --cov.

Pydantic v2

Use Pydantic for all external data boundaries (API I/O, config, queue payloads). Prefer model_validate_json over parse-then-validate. Field(...) for constraints, @field_validator for custom rules.

Code Review Checklist

• Public functions have type hints, no unjustified Any
• Pydantic for external data, X | None not Optional[X]
• Ruff/type checker pass, no bare except:
• Context managers, asyncio.gather() for concurrency
• Async is not concurrent: no single stateful client (e.g. SQLAlchemy AsyncSession) shared across gather() tasks; one session per task via a factory. A shared session corrupts under concurrent use.
• No CPU-bound work inside async def without asyncio.to_thread (parsing, hashing, rendering): it blocks the event loop and serializes every concurrent task. Rule of thumb: a function that awaits nothing probably needs to_thread.
• AAA tests, parametrized

For Docker, CI/CD, async patterns, and detailed testing examples, see references/python-patterns.md.

Resources

Astral: uv, Ruff, ty Python: pytest, Pydantic