python.md

Python Conventions

Style

• Type hints on all function signatures
• Docstrings on public functions (Google style)
• snake_case for functions, variables, modules
• PascalCase for classes
• UPPER_SNAKE_CASE for constants

Example

from dataclasses import dataclass


MAX_RETRIES: int = 3


@dataclass
class UserProfile:
    """A user's profile information."""
    display_name: str
    email: str
    handicap: float | None = None


def calculate_handicap(differentials: list[float], count: int = 20) -> float:
    """Calculate a golf handicap index from scoring differentials.

    Args:
        differentials: List of scoring differentials, most recent first.
        count: Maximum number of differentials to consider.

    Returns:
        The calculated handicap index, rounded to one decimal place.
    """
    recent = differentials[:count]
    best = sorted(recent)[:len(recent) // 2]
    return round(sum(best) / len(best), 1)

Testing

• Framework: pytest
• File naming: test_<module>.py
• Function naming: test_<what>_<condition>_<expected>
• Fixtures for shared setup
• Parametrize for multiple inputs

import pytest
from scoring import calculate_handicap


@pytest.mark.parametrize("diffs, expected", [
    ([10.0, 12.0, 8.0, 11.0], 9.0),
    ([5.5], 5.5),
])
def test_calculate_handicap_returns_average_of_best_half(
    diffs: list[float], expected: float
) -> None:
    assert calculate_handicap(diffs) == expected

Project Structure

project/
  src/
    __init__.py
    main.py
    models.py
  tests/
    test_main.py
    test_models.py
  pyproject.toml
  README.md