"""calc.py - Calculator module providing basic arithmetic operations.

Functions:
    add(a, b): Returns the sum of a and b.
    subtract(a, b): Returns the difference of a and b.
    multiply(a, b): Returns the product of a and b.
    divide(a, b): Returns the quotient of a divided by b.
"""

from typing import Union

Number = Union[int, float]


def _validate_numeric(a: Number, b: Number) -> None:
    """Validate that both arguments are numeric types (int or float, not bool).

    Args:
        a: First operand.
        b: Second operand.

    Raises:
        TypeError: If either operand is not an int or float, or is a bool.
    """
    if isinstance(a, bool) or isinstance(b, bool):
        raise TypeError("Operands must be numeric (int or float), not bool.")
    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
        raise TypeError("Operands must be numeric (int or float).")


def add(a: Number, b: Number) -> Number:
    """Return the sum of two numbers.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The sum of a and b.

    Raises:
        TypeError: If either argument is not a number.
    """
    _validate_numeric(a, b)
    return a + b


def subtract(a: Number, b: Number) -> Number:
    """Return the difference of two numbers (a - b).

    Args:
        a: The first number (minuend).
        b: The second number (subtrahend).

    Returns:
        The difference of a and b.

    Raises:
        TypeError: If either argument is not a number.
    """
    _validate_numeric(a, b)
    return a - b


def multiply(a: Number, b: Number) -> Number:
    """Return the product of two numbers.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The product of a and b.

    Raises:
        TypeError: If either argument is not a number.
    """
    _validate_numeric(a, b)
    return a * b


def divide(a: Number, b: Number) -> float:
    """Return the quotient of two numbers (a / b).

    Args:
        a: The numerator.
        b: The denominator.

    Returns:
        The quotient as a float.

    Raises:
        ZeroDivisionError: If the denominator is zero.
        TypeError: If either argument is not a number.
    """
    _validate_numeric(a, b)
    if b == 0:
        raise ZeroDivisionError("Cannot divide by zero.")
    return a / b


class Calculator:
    """Calculator class providing static and instance access to basic arithmetic operations."""

    @staticmethod
    def add(a: Number, b: Number) -> Number:
        """Return the sum of two numbers."""
        return add(a, b)

    @staticmethod
    def subtract(a: Number, b: Number) -> Number:
        """Return the difference of two numbers (a - b)."""
        return subtract(a, b)

    @staticmethod
    def multiply(a: Number, b: Number) -> Number:
        """Return the product of two numbers."""
        return multiply(a, b)

    @staticmethod
    def divide(a: Number, b: Number) -> float:
        """Return the quotient of two numbers (a / b)."""
        return divide(a, b)