python-stack

Python Engineering Stack

Standard tooling and conventions for Python projects. When making recommendations or scaffolding projects, prefer these tools over alternatives unless the user explicitly requests otherwise.

Python Version

Use Python 3.13 or 3.14. Target the latest stable release for new projects.

Package and Dependency Management

uv is the standard package and dependency manager. It replaces pip, Poetry, and Conda.

• Use uv init to scaffold new projects
• Use uv add <package> to add dependencies (not pip install)
• Use uv sync to install from lockfile
• Use uv run to execute scripts/commands in the project environment
• Use uvx to run CLI tools without installing them (e.g., uvx ruff check, uvx ty)
• pyproject.toml is the single source of truth for project metadata and dependencies

Coding Standards

MUST DO

• Type hints for all function signatures and class attributes
• Use X | None instead of Optional[X] (Python 3.10+)
• PEP 8 compliance (enforced via ruff)
• Comprehensive docstrings in Google style for public APIs
• Test coverage exceeding 90% with pytest
• Async/await for I/O-bound operations
• Dataclasses over manual __init__ methods (or Pydantic models when validation is needed)
• 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 ty errors in strict mode
• Use bare except: clauses
• Hardcode secrets or configuration (use pydantic-settings)
• Use deprecated stdlib modules (use pathlib not os.path)

Code Quality

File Paths — pathlib

Always use pathlib.Path for file and directory operations. Do not use os.path or string manipulation for paths.

Console Output — Rich

Use Rich for terminal output, including formatted text, tables, and progress bars. Use rich.progress as the default for progress indicators.

Logging — Loguru

Use Loguru for application logging. Prefer structured, contextual logs over ad hoc print() debugging.