python-errors-and-logging

name	python-errors-and-logging
description	Use for Python exception design, raising, catching, and logging. Covers narrow `except`, `raise … from …`, domain hierarchies with `Error` suffixes, parameterised logging, `logger.exception`, and the Ruff TRY/BLE/EM/LOG/N818/PERF203 rules.
globs	["**/*.py"]

Python Errors and Logging

Use this when the question is "what should this code raise, catch, or log?" The Ruff rule families (Tryceratops TRY, blind-except BLE, errmsg EM, logging LOG, naming N818, perflint PERF203, bug-bear B017) encode the same decision surface; enforce them in pyproject.toml.

Working stance

• Exceptions are part of the public API; design a small hierarchy with a package base class and *Error suffix (N818).
• Raise specific built-ins (ValueError, TypeError, NotImplementedError) or domain errors; never Exception directly (TRY003, TRY004).
• When wrapping a vendor exception, use raise DomainError(...) from exc (TRY201); when re-raising the same type, plain raise keeps the traceback (TRY200).
• Catch only what can be handled. except Exception: and bare except: are BLE001.
• Use else: for the happy path inside try blocks (TRY300).
• Build exception messages once, then pass them in (EM101/EM102): msg = f"…"; raise X(msg).
• Log once, at a boundary, via a module logger (logger = logging.getLogger(__name__)).

Decision surface

• Raise vs return: raise when the caller cannot continue without policy input; return an Optional/Result-shaped value for expected alternatives (missing cache key, empty page).
• Built-in vs domain error: a built-in suffices when the caller's recovery is "fix the input" (ValueError, TypeError); a domain error is needed when callers must distinguish payment-declined from payment-timeout.
• Wrap vs propagate: wrap at a layer boundary so callers do not import vendor exceptions; propagate inside a layer where the type is already domain-shaped.
• Log vs raise: log at the outermost boundary that has context (request handler, worker entry, CLI main); do not log-and-reraise on every layer.
• Logger call shape: logger.warning("Failed for user_id=%s", uid) — lazy interpolation, module logger, no f-string (LOG004/LOG014), no %-formatting in the format string (LOG007), no logging.warn (LOG009), no root-logger calls (LOG015).
• Hot loops: hoist try/except outside the loop body when the exception is rare (PERF203); when it must stay inside, treat it as a micro-optimisation guided by profiling.

Red flags

• raise Exception(...) or raise RuntimeError(...) where a built-in or domain error fits better,
• except Exception: (or bare except:) with no comment explaining why every exception is recoverable,
• raise NewError(str(exc)) discarding the cause (use from exc),
• logger.exception("…: %s", exc) duplicating the traceback,
• logging.warning(f"…") or logging.warning("… %s" % x),
• pytest.raises(Exception) without a match= regex (B017),
• a try/except wrapping every iteration in a hot loop,
• log-and-reraise chains that emit the same failure at three layers.

Read ruff-rule-map.md and logging-recipes.md for the rule-by-rule mapping and the boundary-logging recipes.