Coding Standards

Guidelines and best practices for contributing to the Definable backend codebase

This guide outlines the coding standards and best practices for the Definable backend codebase. Following these standards ensures code consistency, maintainability, and quality across the project.

Code Formatting and Linting

Ruff

We use Ruff as our primary linter and formatter. Ruff combines many Python linting tools into one fast package.

Our Ruff configuration is defined in ruff.toml at the project root:

indent-width = 2
preview = true
target-version = "py310"

lint.select = [
  "F",  # Pyflakes
  "W6",
  "E71",
  "E72",
  "E112",   # no-indented-block
  "E113",   # unexpected-indentation
  "E203",   # whitespace-before-punctuation
  "E272",   # multiple-spaces-before-keyword
  "E275",   # missing-whitespace-after-keyword
  "E303",   # too-many-blank-lines
  "E304",   # blank-line-after-decorator
  "E501",   # line-too-long
  "E702",   # multiple-statements-on-one-line-semicolon
  "E703",   # useless-semicolon
  "E731",   # lambda-assignment
  "W191",   # tab-indentation
  "W291",   # trailing-whitespace
  "W293",   # blank-line-with-whitespace
  "UP039",  # unnecessary-class-parentheses
  "C416",   # unnecessary-comprehension
  "RET506", # superfluous-else-raise
  "RET507", # superfluous-else-continue
  "A",      # builtin-variable-shadowing, builtin-argument-shadowing, builtin-attribute-shadowing
  "SIM105", # suppressible-exception
  "FURB110",# if-exp-instead-of-or-operator
  "RUF018", # assignment-in-assert
]

line-length = 150

exclude = [
  "docs/",
  "examples/",
  "extra/",
  "tinygrad/runtime/autogen",
  "test/external/mlperf_resnet",
  "test/external/mlperf_unet3d",
]

Key standards enforced by our Ruff configuration:

1. Indentation: Use 2 spaces for indentation (not tabs)
2. Line Length: Maximum 150 characters per line
3. Python Version: Code should be compatible with Python 3.10+
4. Whitespace: No trailing whitespace, consistent spacing around operators

Type Checking with Mypy

We use Mypy for static type checking. Our Mypy configuration is defined in mypy.ini:

[mypy]
warn_unused_configs = True
files = src
ignore_missing_imports = True
check_untyped_defs = True
explicit_package_bases = True
warn_unreachable = True
warn_redundant_casts = True

Key type checking requirements:

1. Type Annotations: All function parameters and return values should have type annotations
2. Imported Types: Use proper imports for types (e.g., from typing import List, Optional, Dict)
3. Pydantic Models: Use properly typed Pydantic models for data validation

Pre-commit Hooks

We use pre-commit to run linting and type-checking automatically before commits. Our pre-commit configuration is in .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: ruff
        name: Ruff (local)
        entry: python3 -m ruff
        language: system
        pass_filenames: true
        types: [python]
        args:
          - check

      - id: mypy
        name: Mypy (local)
        entry: python3 -m mypy
        language: system
        pass_filenames: false
        types: [python]
        args:
          - src/
          - --strict-equality
          - --pretty
          - --show-error-codes
          - --config-file=mypy.ini

To set up pre-commit:

1. Install pre-commit: pip install pre-commit
2. Install hooks: pre-commit install

Code Structure and Organization

Directory Structure

Follow the established directory structure:

src/
├── config/       # Configuration management
├── database/     # Database connection and base models
├── dependencies/ # FastAPI dependencies
├── middlewares/  # HTTP middleware components
├── models/       # SQLAlchemy ORM models
├── schemas/      # Shared Pydantic schemas
├── services/     # Business logic organized by domain
│   └── [feature]/
│       ├── schema.py  # Feature-specific schemas
│       └── service.py # Feature-specific service
├── utils/        # Utility functions
└── app.py        # Application entry point

Import Order

Organize imports in the following order, with a blank line between each group:

1. Standard library imports
2. Third-party library imports
3. Application-specific imports

Example:

from datetime import datetime
from typing import List, Optional, Dict
from uuid import UUID

from fastapi import Depends, HTTPException
from pydantic import BaseModel, Field
from sqlalchemy import select

from database import get_db
from models import MyModel
from services.common import format_response

Naming Conventions

1. Files and Directories: Use snake_case (e.g., user_service.py)
2. Classes: Use PascalCase (e.g., UserService)
3. Functions and Variables: Use snake_case (e.g., get_user_by_id)
4. Constants: Use UPPER_SNAKE_CASE (e.g., MAX_CONNECTIONS)
5. Database Models: Use PascalCase with “Model” suffix (e.g., UserModel)
6. Pydantic Schemas: Use PascalCase with descriptive suffixes:
   • Base schemas: UserBase
   • Create operations: UserCreate
   • Update operations: UserUpdate
   • Responses: UserResponse

Documentation Standards

Docstrings

Use triple-quoted docstrings for modules, classes, and functions:

def get_user_by_id(user_id: UUID) -> UserResponse:
    """
    Retrieve a user by their unique identifier.
    
    Args:
        user_id: The UUID of the user to retrieve
        
    Returns:
        UserResponse object with user details
        
    Raises:
        HTTPException: If user not found (404) or on server error (500)
    """

Comments

• Use comments to explain “why” not “what” when code is not self-explanatory
• Keep comments up-to-date with code changes
• Use complete sentences with proper punctuation

Error Handling

1. HTTP Exceptions: Use FastAPI’s HTTPException with appropriate status codes
2. Validation Errors: Use Pydantic for input validation
3. Database Errors: Catch and handle specific database exceptions
4. Logging: Include appropriate logging for errors with context

Example:

try:
    result = await session.execute(query)
    user = result.scalar_one_or_none()
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)
except SQLAlchemyError as e:
    logger.error(f"Database error when fetching user {user_id}: {str(e)}")
    raise HTTPException(status_code=500, detail="Database error")

Service Design Patterns

Dependency Injection

Use FastAPI’s dependency injection system for:

• Database sessions
• Authentication
• Authorization
• Configuration

Example:

async def get_users(
    offset: int = 0,
    limit: int = 10,
    session: AsyncSession = Depends(get_db),
    user: dict = Depends(RBAC("users", "read")),
) -> PaginatedUserResponse:
    # Implementation

Separation of Concerns

1. Models: Define database structure only
2. Schemas: Handle data validation and serialization
3. Services: Implement business logic
4. API Routes: Handle HTTP concerns only

Testing Standards

All code should include appropriate tests:

1. Unit Tests: Test individual functions and methods
2. Integration Tests: Test interactions between components
3. API Tests: Test HTTP endpoints

Use pytest fixtures for common test setup and async testing support.

Example test:

@pytest.mark.asyncio
async def test_get_user(db_session, test_user):
    # Arrange
    user_service = UserService()
    
    # Act
    result = await user_service.get(test_user.id, session=db_session)
    
    # Assert
    assert result.id == test_user.id
    assert result.name == test_user.name

Contributing Guidelines

Before submitting your code:

1. Ensure all linting and type checking passes: ruff check and mypy src/
2. Write or update tests for your changes
3. Document new features or behavior changes
4. Keep commits focused and with clear messages
5. Rebase your branch on the latest main before requesting review

Common Mistakes to Avoid

1. Circular Imports: Organize imports to prevent circular dependencies
2. Missing Type Annotations: Ensure all functions have proper type hints
3. Undocumented Magic: Avoid complex code without clear documentation
4. Hardcoded Values: Use configuration instead of hardcoding sensitive data
5. Overly Complex Functions: Keep functions focused on a single task

Best Practices

1. Pagination: Always implement pagination for list endpoints
2. Error Details: Provide specific, actionable error messages
3. Defensive Programming: Validate inputs and handle unexpected cases
4. Security: Follow security best practices for authentication and data handling
5. Performance: Be mindful of database query efficiency