Exceptions in depth

Keep the cause: raise ... from

Often you catch a low-level error and raise a clearer one for your callers. Use raise NewError(...) from err so the original isn't lost: the traceback then shows both, joined by "The above exception was the direct cause of the following exception".

import json

class ConfigError(Exception):
    pass

def load_config(text):
    try:
        data = json.loads(text)
    except json.JSONDecodeError as err:
        raise ConfigError("settings file is not valid JSON") from err
    if "currency" not in data:
        err = ConfigError("settings file has no currency")
        err.add_note("Add a line like  \"currency\": \"USD\"  to the file.")
        raise err
    return data

for text in ['{"currency": "USD"}', '{"currency": "USD",}', '{"locale": "en"}']:
    try:
        print(load_config(text))
    except ConfigError as e:
        print(type(e).__name__, "|", e, "| caused by:", type(e.__cause__).__name__ if e.__cause__ else None, "| notes:", getattr(e, "__notes__", []))

err.__cause__ holds the original exception, so a logger or an error tracker can show the whole story. add_note (Python 3.11+) attaches extra lines that appear under the traceback. It's the right place for a hint about how to fix the problem, without cramming everything into the message.

Use raise ... from None when the original error really is noise. And never write except Exception: pass: it hides every bug in the block, including the ones you haven't written yet.

try:
    try:
        {}["missing"]
    except KeyError as err:
        raise ValueError("bad config") from err
except ValueError as e:
    print(type(e.__cause__).__name__, e)

Check first, or just try?

Two styles answer "what if this might fail?". Look before you leap checks first: if key in prices:. Easier to ask forgiveness than permission tries, and handles the failure: try: prices[key] with except KeyError. Python code leans toward the second, for good reasons:

• The check can go stale. if os.path.exists(path): open(path) can still fail if the file is deleted between the two lines. Trying, and handling the error, has no such gap.
• It says the common case first. The code reads as what normally happens, with the unusual case handled separately.
• It avoids doing work twice, like looking a key up once to check and again to use it.

Checking first is better when failure is common rather than exceptional (an if is cheaper than an exception), or when trying has side effects you can't undo, like charging a card. Keep try blocks small: wrap only the line that can fail, so you don't accidentally catch a different error from somewhere else.

class UnknownSku(LookupError):
    pass


def price_of(sku, prices):
    return prices[sku]


print(price_of("TE-101", {"TE-101": 200}))

Many failures at once: ExceptionGroup

An importer that stops at the first bad row is frustrating: fix it, rerun, hit the next one. Better to collect every problem and report them together. Python 3.11 added ExceptionGroup for exactly this: one exception that carries a list of others. The new except* catches the matching ones out of the group, and lets the rest carry on up:

class RowError(Exception):
    def __init__(self, line, message):
        super().__init__(f"line {line}: {message}")
        self.line = line

def check_rows(rows):
    problems = []
    for n, (sku, qty) in enumerate(rows, start=1):
        if len(sku) != 6:
            problems.append(RowError(n, f"bad SKU {sku!r}"))
        if not qty.isdigit():
            problems.append(ValueError(f"line {n}: qty {qty!r} isn't a whole number"))
    if problems:
        raise ExceptionGroup(f"{len(problems)} problems in the file", problems)

try:
    check_rows([("TE-101", "2"), ("TENT", "1"), ("PA-108", "two")])
except* RowError as group:
    print("row errors:", [str(e) for e in group.exceptions])
except* ValueError as group:
    print("value errors:", [str(e) for e in group.exceptions])

Each except* clause receives a smaller group holding only the exceptions it matched, and several clauses can run for one group. That's different from a normal except, which stops at the first match. asyncio.TaskGroup uses the same mechanism to report every failed task, not just the first.

Warnings: still works, but...

Not every problem should stop the program. A warning says "this works for now, but you should change it": an old function name about to be removed, a setting that will change meaning, a suspicious value.

import warnings

def total(prices, vat=None, tax=None):
    if vat is not None:
        warnings.warn("vat= is deprecated; use tax= instead", DeprecationWarning, stacklevel=2)
        tax = vat
    return round(sum(prices) * (1 + (tax or 0)), 2)

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    print(total([10, 20], vat=0.2))
print([f"{w.category.__name__}: {w.message}" for w in caught])

stacklevel=2 points the warning at the line that called total, which is the line the caller needs to change. Libraries use DeprecationWarning to give everyone a release or two to update before the old way is removed. Tests can turn warnings into errors (python -W error, or pytest's settings), so they're noticed long before the removal arrives.

class ImportProblem(Exception):
    def __init__(self, line_no, message):
        super().__init__(f"line {line_no}: {message}")
        self.line_no = line_no

def parse_orders(lines):
    orders, problems = [], []
    for n, line in enumerate(lines, start=1):
        parts = line.split(",")
        if len(parts) != 3:
            problems.append(ImportProblem(n, f"expected 3 fields, got {len(parts)}"))
            continue
        sku, qty, price = (p.strip() for p in parts)
        try:
            orders.append((sku, int(qty), float(price)))
        except ValueError as err:
            problem = ImportProblem(n, f"can't read numbers in {line!r}")
            problem.__cause__ = err
            problems.append(problem)
    if problems:
        raise ExceptionGroup(f"{len(problems)} of {len(lines)} lines failed", problems)
    return orders

lines = ["TE-101, 1, 200", "PA-108, two, 55", "FO-120, 3", "CA-132, 4, 5.00"]
try:
    parse_orders(lines)
except* ImportProblem as group:
    print(group.message)
    for problem in group.exceptions:
        print(" ", problem, "| cause:", type(problem.__cause__).__name__ if problem.__cause__ else "-")