Type Hints, Testing & Code Quality

# Without type hints -- works, but unclear
def add(a, b):
    return a + b

# With type hints -- immediately clear what is expected
def add(a: int, b: int) -> int:
    return a + b

# Variable type hints
name: str = "Alice"
age: int = 25
gpa: float = 3.8
is_student: bool = True

from typing import List, Dict, Tuple, Optional, Union

# Lists of a specific type
def average(numbers: List[float]) -> float:
    """Calculate the average of a list of numbers."""
    return sum(numbers) / len(numbers)

# Dictionaries with typed keys and values
def get_student_grades(roster: Dict[str, List[int]]) -> Dict[str, float]:
    """Convert a roster of grade lists to averages."""
    return {name: sum(grades) / len(grades) for name, grades in roster.items()}

# Tuples with specific element types
def get_coordinates() -> Tuple[float, float]:
    """Return a latitude/longitude pair."""
    return (37.7749, -122.4194)

# Optional: can be the type or None
def find_user(user_id: int) -> Optional[str]:
    """Find a user by ID. Returns None if not found."""
    users = {1: "Alice", 2: "Bob", 3: "Charlie"}
    return users.get(user_id)

# Union: can be one of several types
def normalize(value: Union[int, float, str]) -> float:
    """Convert various inputs to a float."""
    if isinstance(value, str):
        return float(value)
    return float(value)

# Python 3.10+ uses | instead of Union and built-in types instead of typing imports
def normalize(value: int | float | str) -> float:
    """Convert various inputs to a float."""
    if isinstance(value, str):
        return float(value)
    return float(value)

def find_user(user_id: int) -> str | None:
    """Find a user by ID. Returns None if not found."""
    users = {1: "Alice", 2: "Bob"}
    return users.get(user_id)

# Built-in generics (no import needed)
def average(numbers: list[float]) -> float:
    return sum(numbers) / len(numbers)

def get_grades(roster: dict[str, list[int]]) -> dict[str, float]:
    return {name: sum(g) / len(g) for name, g in roster.items()}

# The function we want to test
def celsius_to_fahrenheit(celsius: float) -> float:
    """Convert Celsius temperature to Fahrenheit."""
    return celsius * 9 / 5 + 32

# Tests using assert
assert celsius_to_fahrenheit(0) == 32, "Freezing point should be 32F"
assert celsius_to_fahrenheit(100) == 212, "Boiling point should be 212F"
assert celsius_to_fahrenheit(-40) == -40, "-40 is the same in both scales"

print("All temperature tests passed!")

class Calculator:
    """A simple calculator with history."""

    def __init__(self) -> None:
        # Built-in generic syntax (Python 3.9+). No import needed.
        self.history: list[str] = []

    def add(self, a: float, b: float) -> float:
        result = a + b
        self.history.append(f"{a} + {b} = {result}")
        return result

    def subtract(self, a: float, b: float) -> float:
        result = a - b
        self.history.append(f"{a} - {b} = {result}")
        return result

    def multiply(self, a: float, b: float) -> float:
        result = a * b
        self.history.append(f"{a} * {b} = {result}")
        return result

    def divide(self, a: float, b: float) -> float:
        if b == 0:
            raise ValueError("Cannot divide by zero")
        result = a / b
        self.history.append(f"{a} / {b} = {result}")
        return result


# Test suite
def test_calculator() -> None:
    """Run all calculator tests."""
    calc = Calculator()

    # Test basic operations
    assert calc.add(2, 3) == 5
    assert calc.subtract(10, 4) == 6
    assert calc.multiply(3, 7) == 21
    assert calc.divide(15, 3) == 5.0

    # Test edge cases
    assert calc.add(0, 0) == 0
    assert calc.add(-1, 1) == 0
    assert calc.multiply(0, 1000) == 0

    # Test division by zero raises an error
    try:
        calc.divide(10, 0)
        assert False, "Should have raised ValueError"
    except ValueError as e:
        assert str(e) == "Cannot divide by zero"

    # Test history tracking
    assert len(calc.history) == 7  # 7 operations above (before the error)

    print("All calculator tests passed!")

test_calculator()

# Python linters check your code automatically:

# 1. flake8 -- checks PEP 8 style (line length, whitespace, imports)
# pip install flake8
# flake8 my_script.py

# 2. mypy -- checks type hints for correctness
# pip install mypy
# mypy my_script.py

# 3. black -- auto-formats code to a consistent style
# pip install black
# black my_script.py

# 4. ruff -- ultra-fast linter (replaces flake8 + isort + more)
# pip install ruff
# ruff check my_script.py

# Example: mypy would catch this error without running the code:
# def add(a: int, b: int) -> int:
#     return a + b
#
# result = add("hello", "world")  # mypy error: str is not int

# Python 3.10+: use built-in generics (list, dict) and `X | None` instead of
# Optional[X]. No typing imports needed.

class GradeBook:
    """A grade book that tracks student scores with full type safety."""

    def __init__(self) -> None:
        self._grades: dict[str, list[float]] = {}

    def add_grade(self, student: str, grade: float) -> None:
        """Add a grade for a student."""
        if grade < 0 or grade > 100:
            raise ValueError(f"Grade must be 0-100, got {grade}")
        if student not in self._grades:
            self._grades[student] = []
        self._grades[student].append(grade)

    def get_average(self, student: str) -> float | None:
        """Get a student's average grade, or None if no grades exist."""
        grades = self._grades.get(student)
        if not grades:
            return None
        return sum(grades) / len(grades)

    def get_top_student(self) -> str | None:
        """Get the student with the highest average."""
        if not self._grades:
            return None
        return max(self._grades, key=lambda s: sum(self._grades[s]) / len(self._grades[s]))

    def get_all_averages(self) -> dict[str, float]:
        """Get averages for all students."""
        return {
            student: sum(grades) / len(grades)
            for student, grades in self._grades.items()
        }


def test_grade_book() -> None:
    """Comprehensive tests for GradeBook."""
    gb = GradeBook()

    # Test adding grades
    gb.add_grade("Alice", 95)
    gb.add_grade("Alice", 87)
    gb.add_grade("Bob", 78)
    gb.add_grade("Bob", 82)
    gb.add_grade("Charlie", 92)

    # Test averages
    assert gb.get_average("Alice") == 91.0
    assert gb.get_average("Bob") == 80.0
    assert gb.get_average("Charlie") == 92.0
    assert gb.get_average("Unknown") is None

    # Test top student
    assert gb.get_top_student() == "Charlie"

    # Test all averages
    averages = gb.get_all_averages()
    assert len(averages) == 3
    assert averages["Alice"] == 91.0

    # Test invalid grades
    try:
        gb.add_grade("Alice", -5)
        assert False, "Should reject negative grade"
    except ValueError:
        pass

    try:
        gb.add_grade("Alice", 105)
        assert False, "Should reject grade > 100"
    except ValueError:
        pass

    print("All GradeBook tests passed!")

test_grade_book()