python

Python Engineering Standards

This skill codifies 2026 Python best practices — modern tooling (uv, ruff), strict typing, and idiomatic patterns that produce maintainable, performant code.

1. Project Setup & Structure

Tooling: uv (Not pip/pipenv/poetry)

uv is the standard package manager for Python in 2026. It replaces pip, pipenv, and poetry with a single, fast Rust binary.

uv init <project-name>       # Initialize a new project
uv add <package>              # Add a dependency
uv add --dev <package>        # Add a dev dependency
uv run <command>              # Run a command in the project's venv
uv sync                      # Install all deps from uv.lock
uv python install 3.13        # Install a specific Python version

• ALWAYS commit both pyproject.toml AND uv.lock to version control.
• NEVER use requirements.txt for new projects — it is a legacy pattern.
• NEVER use pip install directly — use uv add to keep the lock file in sync.

Directory Layout: src/ Layout

my-project/
├── .python-version          # Pin Python version (e.g., 3.13)
├── pyproject.toml           # Single source of truth for config
├── uv.lock                  # Deterministic lock file
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── main.py
│       └── models.py
└── tests/
    ├── __init__.py
    ├── conftest.py          # Shared fixtures
    └── test_main.py

• Use src/ layout for packages and production apps — it prevents tests from accidentally importing the local source instead of the installed package.
• Group by domain, not file type — prefer users/, billing/, auth/ over models/, utils/, services/.
• Use kebab-case for directory names, snake_case for Python modules.

pyproject.toml Configuration (PEP 621)

See references/config-templates.md for the standard pyproject.toml template.

2. Type Hints (Mandatory)

Type hints are not optional — they are foundational design tools.