python-error-handling

name	python-error-handling
description	Design Python error paths with narrow exceptions, rollback, contextual logs, and preserved blocker truth. Use when handling retries, verifier outcomes, parser failures, or exception flow in Python services.
metadata	{"triggers":{"files":["**/*.py"],"keywords":["except","exception","retry","rollback","blocker","error handling"]}}

Python Error Handling

Priority: P1 (HIGH)

Rules

• Catch the narrowest exception you can explain.
• Roll back mutable state before re-raising or returning failure status.
• Add context to logs and raised errors without discarding the root cause.
• Preserve blocker truth; do not convert real failure into vague success text.

Recipe

1. Handle expected failures close to the boundary.
2. Re-raise unexpected failures after cleanup.
3. Return structured blocker or verdict data when the caller needs workflow truth.
4. Test timeout, malformed input, and missing-env paths.

Anti-Patterns

• No silent except Exception: pass.
• No broad catch that marks work complete without evidence.
• No duplicate logging at every stack layer.
• No blocker text without owner or next action when the protocol needs both.

References

• Framework Map