Python

Python Guidelines

Standards and best practices for Python development. Follow these guidelines when writing or modifying Python code.

Design Principles

Apply DRY, KISS, and SOLID consistently. Prefer functional methods where relevant; use classes for stateful behavior. Use composition with Protocol classes for interfaces rather than inheritance. Each module should have a single responsibility. Use dependency injection for class dependencies.

Code Style

• Naming: Descriptive yet concise names for variables, methods, and classes
• Documentation: Docstrings for all classes, functions, enums, enum values
• Type hints: Use consistently; avoid Any unless necessary
• Imports: Avoid barrel exports in __init__.py; prefer blank files

Type Annotations

• Use dict, list instead of typing.Dict, typing.List
• Use str | None instead of Optional[str]
• Include from __future__ import annotations at top of files with type hints
• Prefer built-in types over typing module equivalents

Architecture

Dependency Injection

• Always inject dependencies via constructors or methods when using classes
• One service class per module (interface and class models allowed in addition)
• Use Protocol classes to define interfaces for dependency injection and testing

Module Organization

• Each module focuses on one concern with clear boundaries
• Extract reusable methods to avoid duplication
• Design for reusability across contexts

Environment Variables

• Use an environment.py file with individual methods per variable (e.g., api_key() for API_KEY, database_url() for DATABASE_URL)
• Co-locate all environment access in one place per package for easier mocking in tests

Data Models

• Use Pydantic v2 for schemas, validation, and data models
• Leverage Pydantic's type validation, serialization, and configuration management
• Use Pydantic models for API request/response schemas, configuration objects, and data transfer objects

Testing

Structure

• Tests mirror src/ directory structure
• Test methods start with test_
• Use test class suites: for def foo() create class TestFoo
• Keep names concise, omit class suite name from method
• Always check for appropriate unit tests when changing code

Quality

• Use AAA (Arrange, Act, Assert) pattern
• Tests should be useful, readable, concise, maintainable
• Avoid tests that create massive diffs or become burdensome

Tools

• Prefer pytest over unittest
• Use pytest-mock for mocking
• Use conftest.py for shared fixtures
• Use tests/__test_<package_name>__ for shared testing code

Implementation

When implementing Python code:

• Ensure code passes type checking and tests before committing
• Group related changes with tests in atomic commits
• Check for existing workflow patterns (spec-first, TDD, etc.) and follow them

References

• For adhoc Python scripts in uv-managed projects, see references/uv-scripts.md.
• For monorepo-specific patterns using uv and Hatch, see references/uv-monorepo.md.

Python Monorepo Guidelines

Guidelines for Python monorepos managed by uv with Hatch as the build system.

Project Structure

Layout

• Root workspace at repository root
• Packages under packages/ directory
• Shared config in root pyproject.toml
• Workspace tasks in root justfile
• Package tasks in individual justfiles

Package Structure

Required structure for each package:

packages/<package-name-kebab-case>/
├── pyproject.toml         # Config and dependencies
├── justfile               # Package-specific tasks
├── src/
│   └── <package_name_snake_case>/  # Python module
│       ├── main.py
│       └── <submodule>/   # Submodules in snake_case
└── tests/                 # Mirrors src structure
    └── _integration/      # Integration tests (if package exposes API/CLI/interface etc)

Naming: Directories use kebab-case; Python modules and submodules use snake_case

Build System

• Build backend: Hatch (pypa/hatch)
• Versioning: hatch-vcs (ofek/hatch-vcs) from git tags
• Package versions auto-derived from git tags

Dependency Management

• Tool: ALWAYS use uv. NEVER use pip or other tools directly
• Root dependencies: Available to all packages
• Sync: Use uv sync to install/sync
• Package dependencies: Specify in individual pyproject.toml
• Dev dependencies: Use [dependency-groups] in pyproject.toml

Package Organization

Cross-Package Dependencies

• Reference workspace packages in pyproject.toml
• Extract common functionality into a shared core package
• Establish clear dependency hierarchy; avoid circular dependencies

Package Boundaries

• Each package is independently buildable and testable
• Expose only necessary APIs or CLIs through public interfaces
• Keep implementation details private within modules
• Place shared utilities in dedicated packages

Testing

Integration Tests

• Packages exposing APIs or CLIs should include integration tests
• Place integration tests in tests/_integration/ directory
• Integration tests verify end-to-end behavior of public interfaces
• Keep integration tests in the package that exposes the functionality
• Integration tests with costs, or involved setup, should be enabled through an environment variable

uv Scripts Guidelines

Guidelines for adhoc Python scripts in uv-managed projects. Use uv's inline script metadata (PEP 723) to ensure dependencies are source controlled and scripts are executable.

Declaring Script Dependencies

Use uv add --script to declare dependencies inline in the script file:

uv add --script script.py 'requests<3' 'rich'

This adds inline metadata at the top of the script:

# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint
# ... rest of script

Executable Scripts with Shebang

For executable scripts, use the shebang format that works with uv:

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

import httpx
# ... rest of script

Make scripts executable with chmod +x script.py, then run directly: ./script.py

Running Scripts

• Use uv run script.py to execute scripts (uv automatically manages the environment)
• Scripts with inline metadata ignore project dependencies (no need for --no-project flag)
• Use uv lock --script script.py to create a lockfile (script.py.lock) for reproducibility

Best Practices

• Always declare dependencies inline for adhoc scripts to ensure they're source controlled
• Use shebang (#!/usr/bin/env -S uv run --script) for executable scripts
• Lock dependencies using uv lock --script for reproducibility
• Specify Python version in metadata if required: requires-python = ">=3.12"

References

Based on uv documentation on declaring script dependencies.