Code Style Guide¶

Python code style guidelines for maintaining consistent, readable code across the project.

Style Guidelines¶

PEP 8 Compliance¶

Follow PEP 8 with these specifics:

Line length: 100 characters (Ruff configuration)
Indentation: 4 spaces
Use double quotes for strings
Trailing commas in multi-line structures

Type Hints¶

Always use type hints:

from typing import List, Dict, Any

def analyze_sentiment(text: str, top_k: int = 5) -> Dict[str, Any]:
    """Analyze sentiment of input text."""
    pass

Docstrings¶

Use Google-style docstrings:

def example_function(param1: str, param2: int) -> bool:
    """Short description.

    Longer description if needed.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        Description of return value.

    Raises:
        ValueError: When param2 is negative.
    """
    pass

Import Order¶

Standard library
Third-party packages
Local modules

Use ruff check --select I --fix to auto-sort imports.

Naming Conventions¶

Classes: PascalCase (RAGService, SentimentAnalyzer)
Functions: snake_case (extract_topics, calculate_confidence)
Constants: UPPER_SNAKE_CASE (MAX_RETRIES, DEFAULT_TOP_K)
Private: Prefix with underscore (_internal_method, _cache)

Tools & Automation¶

The project uses modern Python tooling for code quality:

Ruff - Fast linting and code quality checks
Ruff Formatter - Consistent code formatting (Black-compatible)
Mypy - Static type checking
pytest - Testing framework with coverage
Bandit - Security vulnerability scanning

See individual guides for detailed usage:

Linting Guide - Ruff, Mypy, Bandit
Formatting Guide - Ruff formatter
Testing Guide - pytest, coverage, fixtures

Formatting Tools¶

Ruff¶

Ruff is used for both linting and formatting:

# Lint code
uv run ruff check src/ tests/

# Auto-fix issues (including import sorting)
uv run ruff check --fix src/ tests/

# Format code
uv run ruff format src/ tests/

# Check formatting without changes
uv run ruff format --check src/ tests/

For detailed usage and configuration, see:

Linting Guide - Complete linting documentation
Formatting Guide - Code formatting standards

Testing Guide - Test practices and coverage
Linting Guide - Code quality checks
Formatting Guide - Code formatting standards
CI/CD Local Testing - Running CI checks locally

Pre-commit Hooks¶

Automatically run checks before commits:

# Install hooks
uv run pre-commit install

# Run manually
uv run pre-commit run --all-files

Best Practices¶

Keep functions small - Single responsibility principle
Use descriptive names - Self-documenting code
Avoid magic numbers - Use named constants
Handle errors explicitly - Don't hide exceptions
Write testable code - Dependency injection
Document complex logic - Add inline comments