raise and assert in Python — When, Why and How to Use Them Right

def register_user(username: str, age: int) -> dict:
    """
    Registers a new user. Raises informative errors if the input is invalid.
    """
    # Check for the wrong TYPE first — age should be an integer, not a string
    if not isinstance(age, int):
        raise TypeError(
            f"age must be an integer, got {type(age).__name__} instead"
        )

    # Check for the wrong VALUE — technically an int, but makes no real-world sense
    if age < 0 or age > 130:
        raise ValueError(
            f"age must be between 0 and 130, got {age}"
        )

    # Check username isn't empty — a blank name would corrupt our database records
    if not username or not username.strip():
        raise ValueError("username cannot be empty or whitespace")

    # All checks passed — safe to build the user record
    return {"username": username.strip(), "age": age, "status": "registered"}


# --- Demo: what happens with valid and invalid inputs ---

try:
    result = register_user("alice", 28)
    print(f"Success: {result}")
except (TypeError, ValueError) as error:
    print(f"Registration failed: {error}")

try:
    result = register_user("bob", -5)   # Nonsensical age
    print(f"Success: {result}")
except (TypeError, ValueError) as error:
    print(f"Registration failed: {error}")

try:
    result = register_user("   ", 25)   # Blank username
    print(f"Success: {result}")
except (TypeError, ValueError) as error:
    print(f"Registration failed: {error}")

try:
    result = register_user("carol", "twenty")  # Wrong type entirely
    print(f"Success: {result}")
except (TypeError, ValueError) as error:
    print(f"Registration failed: {error}")

# --- Custom Exception Hierarchy ---

class PaymentError(Exception):
    """Base exception for all payment-related failures in this module."""
    pass

class InsufficientFundsError(PaymentError):
    """Raised when an account doesn't have enough balance to cover a charge."""
    def __init__(self, account_id: str, required: float, available: float):
        self.account_id = account_id
        self.required = required
        self.available = available
        # Store structured data AND give a clear human-readable message
        super().__init__(
            f"Account {account_id} needs ${required:.2f} but only has ${available:.2f}"
        )

class CardDeclinedError(PaymentError):
    """Raised when the payment network explicitly rejects the card."""
    def __init__(self, card_last_four: str, reason: str):
        super().__init__(f"Card ending in {card_last_four} was declined: {reason}")


# --- The function that uses them ---

def process_payment(account_id: str, amount: float, card_last_four: str) -> str:
    # Simulate fetching the account balance from a database
    mock_balances = {"ACC001": 120.00, "ACC002": 30.00}

    if account_id not in mock_balances:
        # Wrap a lookup failure in a domain-meaningful exception
        try:
            raise KeyError(account_id)
        except KeyError as lookup_error:
            # 'raise ... from' chains the original error — traceback is preserved
            raise PaymentError(
                f"Account {account_id} not found"
            ) from lookup_error

    balance = mock_balances[account_id]

    if balance < amount:
        raise InsufficientFundsError(account_id, amount, balance)

    # Simulate a random network decline for demo purposes
    if card_last_four == "0000":
        raise CardDeclinedError(card_last_four, "do-not-honour flag from issuer")

    return f"Payment of ${amount:.2f} approved for account {account_id}"


# --- Callers can now be as specific or broad as they need ---

for account, amount, card in [
    ("ACC001", 50.00, "1234"),   # Should succeed
    ("ACC002", 50.00, "5678"),   # Insufficient funds
    ("ACC001", 50.00, "0000"),   # Card declined
    ("ACC999", 50.00, "1234"),   # Account not found
]:
    try:
        message = process_payment(account, amount, card)
        print(f"OK: {message}")
    except InsufficientFundsError as e:
        # We can access structured data, not just the string message
        print(f"FUNDS ERROR — shortfall: ${e.required - e.available:.2f}")
    except CardDeclinedError as e:
        print(f"CARD ERROR: {e}")
    except PaymentError as e:
        # Catches anything else in the PaymentError family
        print(f"PAYMENT ERROR: {e}")

def calculate_weighted_average(values: list, weights: list) -> float:
    """
    Calculates a weighted average. Both lists must be the same length
    and weights must sum to 1.0. These are developer contracts, not
    user-facing validation — so we use assert, not raise.
    """
    # ASSERT: This is a programmer contract. If lengths differ, the calling
    # code has a bug. We want to catch this instantly during development.
    assert len(values) == len(weights), (
        f"values and weights must be the same length: "
        f"got {len(values)} values and {len(weights)} weights"
    )

    # ASSERT: Weights that don't sum to ~1.0 mean our math will silently produce
    # wrong results. Catching this beats debugging mysterious output later.
    total_weight = sum(weights)
    assert abs(total_weight - 1.0) < 1e-9, (
        f"weights must sum to 1.0, got {total_weight}"
    )

    # The actual calculation — safe to proceed because our contracts hold
    weighted_sum = sum(v * w for v, w in zip(values, weights))

    # POST-CONDITION assert: the result must be within the range of input values
    # If this fails, our algorithm itself is broken — not the inputs
    assert min(values) <= weighted_sum <= max(values), (
        f"result {weighted_sum} is outside the range of input values — "
        "this is a logic bug in this function"
    )

    return weighted_sum


# --- Valid usage ---
exam_scores = [95, 72, 88]
# Midterm 20%, Final 50%, Assignment 30%
score_weights = [0.20, 0.50, 0.30]
final_grade = calculate_weighted_average(exam_scores, score_weights)
print(f"Weighted grade: {final_grade:.2f}")

# --- This reveals a programmer error immediately ---
try:
    bad_result = calculate_weighted_average(
        [95, 72, 88],
        [0.20, 0.50]    # Forgot the third weight — a bug in the calling code
    )
except AssertionError as error:
    print(f"AssertionError caught (dev bug, not user error): {error}")

import json

# ============================================================
# raise: for conditions that can happen legitimately at runtime
# ============================================================

def load_product_catalog(filepath: str) -> dict:
    """
    Loads product data from a JSON file.
    File-not-found and bad JSON are EXPECTED failure modes —
    they happen in production. Use raise.
    """
    try:
        with open(filepath, "r") as file:
            catalog = json.load(file)
    except FileNotFoundError:
        # Re-raise with a more useful message for the caller
        raise FileNotFoundError(
            f"Product catalog not found at '{filepath}'. "
            "Check the path and ensure the file was deployed."
        )
    except json.JSONDecodeError as parse_error:
        raise ValueError(
            f"Catalog file at '{filepath}' contains invalid JSON."
        ) from parse_error

    return catalog


def apply_discount(product: dict, discount_rate: float) -> dict:
    """
    Applies a discount to a product dict. The discount_rate comes from
    user input, so invalid values are expected. Use raise.
    """
    if not 0.0 <= discount_rate <= 1.0:
        raise ValueError(
            f"discount_rate must be between 0.0 and 1.0, got {discount_rate}"
        )
    discounted_price = product["price"] * (1 - discount_rate)
    return {**product, "price": round(discounted_price, 2), "discounted": True}


# ============================================================
# assert: for internal logic invariants — developer contracts
# ============================================================

def split_inventory_into_batches(items: list, batch_size: int) -> list:
    """
    Splits an item list into equal-sized batches for warehouse processing.
    This is an internal utility. We control all callers.
    """
    # ASSERT: We control every caller of this function. If batch_size <= 0
    # arrives here, the calling code has a logic bug — not user error.
    assert batch_size > 0, f"batch_size must be positive, got {batch_size}"

    batches = [items[i:i + batch_size] for i in range(0, len(items), batch_size)]

    # POST-CONDITION: reassembling batches must recreate the original list
    # If this fails, our batching algorithm has a bug
    assert sum(len(b) for b in batches) == len(items), (
        "Batching produced a different number of items than the input — logic error"
    )

    return batches


# --- Demonstration ---

# raise in action — invalid user-supplied discount rate
product = {"name": "Widget Pro", "price": 99.99}
try:
    result = apply_discount(product, 1.5)   # 150% discount — clearly wrong
except ValueError as e:
    print(f"Discount error (user input problem): {e}")

# Valid discount
discounted = apply_discount(product, 0.20)
print(f"After 20% off: ${discounted['price']}")

# assert in action — correct internal usage
warehouse_items = ["SKU001", "SKU002", "SKU003", "SKU004", "SKU005"]
batches = split_inventory_into_batches(warehouse_items, batch_size=2)
print(f"Batches: {batches}")

# assert catching a developer mistake
try:
    bad_batches = split_inventory_into_batches(warehouse_items, batch_size=0)
except AssertionError as e:
    print(f"AssertionError (developer bug): {e}")