Python Type Hints — Optional Without Guard Crashes Payment

# basic_annotations.py
# Demonstrates variable annotations and function signatures
# with simple built-in types, and a type alias using the 3.12+ type statement.

from __future__ import annotations

# ── 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

# ── Type alias (Python 3.12+ style) ───────────────────────────────────────
type Price = float
type DiscountPercent = float


# ── Annotated function: inputs AND output are typed ──────────────────────
def calculate_discount(original_price: Price, discount_percent: DiscountPercent) -> Price:
    """
    Returns the final price after applying a percentage discount.
    Both arguments and the return value are floats.
    """
    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.
# Uses Python 3.10+ pipe syntax for unions and match statement for type narrowing.

from __future__ import annotations
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 (pipe syntax) ─────
def get_user_flexible(identifier: int | str) -> dict[str, str] | None:
    """
    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


# ── Using match for type narrowing ────────────────────────────────────────
def greet_user(identifier: int | str) -> str:
    user = get_user_flexible(identifier)
    match user:
        case None:
            return "User not found."
        case _:
            return f"Hello, {user['username']}!"


# ── Literal: restrict to a known set of string values ─────────────────────
type 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

# generics_typevar.py
# Demonstrates TypeVar, the new Python 3.12 generic syntax, and Self type.

from __future__ import annotations
from typing import TypeVar, Generic, Optional
from typing import Self  # Python 3.11+

# ── TypeVar: T is a placeholder for "any one specific type" ───────────────
T = TypeVar("T")  # Unconstrained: works with any type


# ── Python 3.12+ generic function syntax (alternative to TypeVar) ────────
# This is equivalent to: def get_first(items: list[T]) -> T | None
# but uses the new type parameter list

def get_first[T](items: list[T]) -> T | None:
    """
    Returns the first element of any list, or None if empty.
    If you pass list[str], you get back str | None.
    If you pass list[int], you get back int | None.
    """
    return items[0] if items else None


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

    def __init__(self, value: T | None = None, error: str | None = 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}")
        # We know _value is not None here, but type checker may need help
        assert self._value is not None
        return self._value

    def map[U](self, func: Callable[[T], U]) -> Result[U]:
        """Apply a function to the value if present."""
        if self._error is not None:
            return Result(error=self._error)
        return Result(value=func(self._value))

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


# ── Using Self for builder pattern ───────────────────────────────────────
class UserBuilder:
    def __init__(self) -> None:
        self._name: str = ""

    def with_name(self, name: str) -> Self:
        """Returns Self so subclasses can chain methods and keep the correct type."""
        self._name = name
        return self

    def build(self) -> dict[str, str]:
        return {"name": self._name}


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

good_result = Result(value=28)
bad_result  = Result(error="Invalid input")

print(good_result)           # Result.ok(28)
print(good_result.unwrap())  # 28
print(bad_result)            # Result.err('Invalid input')
print(bad_result.is_ok)      # False

# Self demo
builder = UserBuilder().with_name("Alice")
user = builder.build()
print(f"Built user: {user}")

# 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


# ── 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) -> Invoice | None:
    """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 "Invoice | None" 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}")