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