Python Type Hints Explained — Annotations, Generics and Real-World Patterns

# basic_annotations.py
# Demonstrates variable annotations and function signatures
# with simple built-in types.

# ── Variable annotations ──────────────────────────────────────────────────
max_retries: int = 3          # This variable should always be an integer
service_name: str = "payments" # A plain string label
is_debug_mode: bool = False    # Boolean flag


# ── Annotated function: inputs AND output are typed ──────────────────────
def calculate_discount(original_price: float, discount_percent: float) -> float:
    """
    Returns the final price after applying a percentage discount.
    Both arguments and the return value are floats.
    """
    # We use the annotations as documentation — mypy checks them for us
    discount_amount = original_price * (discount_percent / 100)
    final_price = original_price - discount_amount
    return final_price


# ── A function that returns nothing uses -> None ──────────────────────────
def log_event(event_name: str, severity: int) -> None:
    """
    Logs an application event. Returns nothing — annotated with None.
    Forgetting -> None looks sloppy and confuses tools.
    """
    print(f"[severity={severity}] {event_name}")


# ── Python stores annotations but does NOT enforce them at runtime ────────
def add_scores(score_a: int, score_b: int) -> int:
    return score_a + score_b

# This runs fine at runtime even though we pass floats — Python won't stop us.
# But mypy would flag this as an error: Argument 1 to "add_scores" has
# incompatible type "float"; expected "int"
result = add_scores(9.5, 8.5)  # mypy ERROR, but Python runs it anyway


# ── Inspecting annotations at runtime ────────────────────────────────────
print(calculate_discount.__annotations__)
print(f"Discount applied: £{calculate_discount(100.0, 15.0):.2f}")
log_event("user_login", severity=2)

# optional_union_literal.py
# Shows Optional, Union, and Literal in a realistic user-lookup scenario.

from __future__ import annotations  # Enables postponed evaluation for older Python
from typing import Optional, Union, Literal

# ── Simulated database of users ───────────────────────────────────────────
_user_store: dict[int, dict[str, str]] = {
    1: {"username": "alice", "role": "admin"},
    2: {"username": "bob",   "role": "viewer"},
}


# ── Optional: the user might not exist ────────────────────────────────────
def find_user_by_id(user_id: int) -> Optional[dict[str, str]]:
    """
    Returns the user dict if found, or None if the ID doesn't exist.
    Callers MUST check for None before using the result.
    """
    return _user_store.get(user_id)  # dict.get returns None if key is missing


# ── Union: accept either an int ID or a string username ───────────────────
def get_user_flexible(identifier: Union[int, str]) -> Optional[dict[str, str]]:
    """
    Accepts either a numeric ID or a username string.
    Returns the matching user or None.
    """
    if isinstance(identifier, int):
        return find_user_by_id(identifier)

    # Search by username string
    for user in _user_store.values():
        if user["username"] == identifier:
            return user
    return None


# ── Python 3.10+ shorthand: int | str instead of Union[int, str] ──────────
def greet_user(identifier: int | str) -> str:
    user = get_user_flexible(identifier)
    if user is None:
        return "User not found."
    return f"Hello, {user['username']}!"


# ── Literal: restrict to a known set of string values ─────────────────────
PermissionLevel = Literal["read", "write", "admin"]

def set_permission(user_id: int, level: PermissionLevel) -> None:
    """
    Only 'read', 'write', or 'admin' are valid levels.
    mypy will error if you pass 'superuser' or any other string.
    """
    print(f"User {user_id} granted '{level}' permission.")


# ── Demo ──────────────────────────────────────────────────────────────────
print(greet_user(1))            # Lookup by int
print(greet_user("bob"))        # Lookup by string
print(greet_user(99))           # Missing user

set_permission(1, "admin")      # Valid — mypy is happy
# set_permission(1, "superuser") # mypy ERROR: Argument 2 has incompatible type
                                  # "Literal['superuser']"; expected
                                  # "Literal['read', 'write', 'admin']"

# generics_typevar.py
# Demonstrates TypeVar for reusable typed utilities and a simple
# generic Result wrapper — a common real-world pattern.

from __future__ import annotations
from typing import TypeVar, Generic, Optional

# ── TypeVar: T is a placeholder for "any one specific type" ───────────────
T = TypeVar("T")  # Unconstrained: works with any type
NumberT = TypeVar("NumberT", int, float)  # Constrained: only int or float


# ── A simple generic function ─────────────────────────────────────────────
def get_first_item(items: list[T]) -> Optional[T]:
    """
    Returns the first element of any list, or None if empty.
    If you pass list[str], you get back Optional[str].
    If you pass list[int], you get back Optional[int].
    The return type MIRRORS the input — that's the power of TypeVar.
    """
    return items[0] if items else None


# ── A constrained TypeVar function ────────────────────────────────────────
def clamp(value: NumberT, minimum: NumberT, maximum: NumberT) -> NumberT:
    """
    Clamps a number between min and max.
    Works for both int and float, but won't accept strings.
    mypy would flag clamp('hello', 'a', 'z') as an error.
    """
    return max(minimum, min(value, maximum))


# ── Generic class: a Result wrapper (like Rust's Result type) ─────────────
class Result(Generic[T]):
    """
    Wraps either a successful value of type T, or an error message.
    Used instead of raising exceptions for expected failure cases
    (e.g. form validation, external API calls).
    """

    def __init__(self, value: Optional[T] = None, error: Optional[str] = None) -> None:
        self._value = value
        self._error = error

    @property
    def is_ok(self) -> bool:
        return self._error is None

    def unwrap(self) -> T:
        """Returns the value or raises if there was an error."""
        if self._error is not None:
            raise ValueError(f"Tried to unwrap an error result: {self._error}")
        return self._value  # type: ignore[return-value]

    def __repr__(self) -> str:
        if self.is_ok:
            return f"Result.ok({self._value!r})"
        return f"Result.err({self._error!r})"


# ── Factory helpers keep call sites clean ────────────────────────────────
def ok(value: T) -> Result[T]:
    return Result(value=value)

def err(message: str) -> Result:  # No T needed — error carries no typed value
    return Result(error=message)


# ── Realistic usage: parsing a user-submitted age ─────────────────────────
def parse_age(raw_input: str) -> Result[int]:
    """
    Returns Result[int] on success, Result with error on failure.
    Caller checks .is_ok before calling .unwrap() — no try/except needed.
    """
    if not raw_input.isdigit():
        return err(f"'{raw_input}' is not a valid integer")
    age = int(raw_input)
    if not (0 < age < 130):
        return err(f"Age {age} is outside the plausible range")
    return ok(age)


# ── Demo ──────────────────────────────────────────────────────────────────
print(get_first_item(["alpha", "beta", "gamma"]))  # str list → str returned
print(get_first_item([42, 100, 7]))                # int list → int returned
print(get_first_item([]))                          # Empty list → None

print(clamp(150, 0, 100))   # Clamps int to 100
print(clamp(3.7, 1.0, 5.0)) # Works with floats too

good_result = parse_age("28")
bad_result  = parse_age("abc")

print(good_result)           # Result.ok(28)
print(good_result.unwrap())  # 28
print(bad_result)            # Result.err("'abc' is not a valid integer")
print(bad_result.is_ok)      # False

# mypy_in_action.py
# A realistic example showing bugs that mypy catches BEFORE runtime.
# Run: mypy mypy_in_action.py --strict

from __future__ import annotations
from typing import Optional


# ── Data model ────────────────────────────────────────────────────────────
class Invoice:
    def __init__(self, invoice_id: int, amount_gbp: float, paid: bool) -> None:
        self.invoice_id = invoice_id
        self.amount_gbp = amount_gbp
        self.paid = paid

    def mark_paid(self) -> None:
        self.paid = True
        print(f"Invoice #{self.invoice_id} marked as paid.")


# ── Service layer ─────────────────────────────────────────────────────────
_invoice_db: dict[int, Invoice] = {
    101: Invoice(101, 499.99, False),
    102: Invoice(102, 120.00, True),
}


def fetch_invoice(invoice_id: int) -> Optional[Invoice]:
    """Returns the Invoice or None if not found."""
    return _invoice_db.get(invoice_id)


def process_payment(invoice_id: int) -> str:
    """
    Marks an invoice paid and returns a confirmation string.
    This is where beginners make the classic Optional mistake.
    """
    invoice = fetch_invoice(invoice_id)

    # ── BUG: calling .mark_paid() without checking for None ──────────────
    # Uncomment the next line and run mypy — it catches it immediately:
    # invoice.mark_paid()  # mypy: Item "None" of "Optional[Invoice]" has no attribute "mark_paid"

    # ── CORRECT: narrow the type with an explicit None check ─────────────
    if invoice is None:
        return f"Invoice #{invoice_id} not found."

    # After the None check, mypy knows `invoice` is definitely an Invoice
    invoice.mark_paid()  # Safe — mypy is satisfied here
    return f"Payment processed for £{invoice.amount_gbp:.2f}."


def get_overdue_total(invoice_ids: list[int]) -> float:
    """
    Sums the outstanding amounts for a list of invoice IDs.
    Demonstrates how narrowing keeps your accumulator type clean.
    """
    total: float = 0.0

    for invoice_id in invoice_ids:
        invoice = fetch_invoice(invoice_id)
        if invoice is not None and not invoice.paid:
            total += invoice.amount_gbp  # mypy knows invoice is Invoice here

    return total


# ── Demo ──────────────────────────────────────────────────────────────────
print(process_payment(101))      # Valid invoice, unpaid
print(process_payment(999))      # Missing invoice

overdue = get_overdue_total([101, 102, 103])
print(f"Total overdue: £{overdue:.2f}")