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]