Waldur Code Style Guide
Import Organization
- Standards: Use
isort
with sections: future, standard-library, first-party, third-party, local-folder
- Placement: ALWAYS place all imports at the top of the module
- Inline Imports: NEVER use inline imports within functions or methods (except for dynamic imports when absolutely necessary)
- Formatter: Follow ruff formatting rules
- Line Length: Line length restrictions are ignored (E501)
- Indentation: Use 4 spaces, never tabs
Type Hints
- Version: Python 3.10+ compatibility
- Usage: Use type hints where possible
- Modern Syntax: Use
dict[str, str]
instead of Dict[str, str]
Naming Conventions
- Functions/Variables: Use snake_case
- Classes: Use CamelCase
- Constants: Use UPPER_SNAKE_CASE
- Django Models: Follow Django conventions
- Private: Prefix with underscore for internal use
Error Handling
- Core Exceptions: Use exceptions from
waldur_core.core.exceptions
- Logging: Add appropriate logging for errors
- Context: Include debugging context in error messages
- Re-raising: Preserve original traceback when re-raising
Documentation
- Docstrings: Required for public methods and classes
- Comments: Avoid unnecessary comments - code should be self-documenting
- TODO: Use
# TODO:
format with description and owner
Testing
- Unit Tests: For complex functions
- API Tests: For all endpoints
- Directory Structure: Follow existing test directory structure
- Naming: Test files should match module names with
test_
prefix
Serializers
- REST Conventions: Follow Django REST Framework patterns
- Relationships: Use HyperlinkedRelatedField for relationships
- Query Optimization: Implement
eager_load()
methods
- UUID Fields: ALWAYS use
SlugRelatedField(slug_field="uuid")
instead of PrimaryKeyRelatedField
API Schema
- Type Annotations: Use modern syntax (e.g.,
dict[str, str]
)
- Response Documentation: Avoid verbose dictionary literals
- Simple Actions: Omit unnecessary
responses={status.HTTP_200_OK: None}
- OpenAPI: Use
@extend_schema
decorators appropriately
Markdown Documentation
- Linting: ALL markdown must pass
mdl --style markdownlint-style.rb <path>
- List Indentation: Use exactly 2 spaces for nested items
- Consistency: Maintain consistent formatting throughout
API Design Consistency
- Default Parameters: Choose defaults that match most common use case
- Error Hierarchy:
- Configuration errors (AttributeError) for invalid code/setup
- Permission errors (PermissionDenied) for access control
- Validation errors for user input
- Function Signatures: Document parameter behavior clearly, especially optional parameters
Important Guidelines
- No Emojis: Avoid emojis unless explicitly requested
- Avoid "Comprehensive": Don't use this word in documentation
- Incremental Changes: Make small, testable changes
- Existing Patterns: Follow established project patterns