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.