Code Style Guide

Python code style guidelines for the Are You Not Entertained (AYNE) project.

Style Guidelines

PEP 8 Compliance

Follow PEP 8 with these specifics:

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

Type Hints

Always use type hints:

def process_data(year: int, month: int) -> pd.DataFrame:
    """Process data for given period."""
    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

1. Standard library
2. Third-party packages
3. Local modules

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

Naming Conventions

• Classes: PascalCase (WeightProcessor)
• Functions: snake_case (process_weights)
• Constants: UPPER_SNAKE_CASE (MAX_RETRIES)
• Private: Prefix with underscore (_internal_method)

Tools & Automation

The AYNE project uses modern Python tooling for code quality:

• Ruff - Fast linting and code quality checks
• Ruff Formatter - Consistent code formatting
• Mypy - Static type checking
• pytest - Testing framework with coverage
• Pre-commit - Automated checks before commits

See individual guides for detailed usage:

• Linting Guide - Ruff, Mypy, Bandit
• Formatting Guide - Ruff formatter, pre-commit
• 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

Related Documentation

• Testing Guide - Test practices and coverage
• Linting Guide - Code quality checks
• Formatting Guide - Code formatting standards
• GitHub Actions Workflows - See .github/workflows/ for automated quality checks

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

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