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_
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.