Lukas
2f9fc8076d
- Extract jail status/processing to helper functions - Add error_handling.py service for centralized error handling - Update config.py with validation and defaults - Update .env.example with all config options - Remove obsolete Tasks.md, add Service-Development.md - Minor fixes across routers and services Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
65 lines
2.4 KiB
Python
65 lines
2.4 KiB
Python
"""Error handling contracts for services.
|
|
|
|
Defines the three allowed error handling patterns so callers know what to
|
|
expect from any service method.
|
|
|
|
Pattern Selection
|
|
================
|
|
- ABORT_ON_ERROR: Operations where failure must propagate (auth, writes, config changes)
|
|
- RETURN_DEFAULT: Informational reads where partial data is acceptable
|
|
- PARTIAL_RESULT: Operations on collections where some items may fail independently
|
|
|
|
Switching patterns is a breaking change — document in changelog.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
ABORT_ON_ERROR = "abort_on_error"
|
|
"""Raise an exception. Router converts to HTTP. Use for auth, writes, state changes."""
|
|
|
|
RETURN_DEFAULT = "return_default"
|
|
"""Return empty result and log warning. Never raises. Use for informational reads."""
|
|
|
|
PARTIAL_RESULT = "partial_result"
|
|
"""Return (result, errors) tuple. Use for batch operations on collections."""
|
|
|
|
|
|
class ServiceErrorContract:
|
|
"""Documents the error handling pattern for a service or method.
|
|
|
|
Callers use this to understand how errors affect the return value:
|
|
|
|
ABORT_ON_ERROR
|
|
Raise an exception. Router handles it, converts to HTTP response.
|
|
Used for: authentication, authorization, write operations,
|
|
state changes, and any operation where partial success is meaningless.
|
|
|
|
RETURN_DEFAULT
|
|
Return empty/None result and log a warning. Caller gets a valid
|
|
result with no items, not an error.
|
|
Used for: informational reads (list, get) where infrastructure
|
|
unavailability should not block the UI.
|
|
|
|
PARTIAL_RESULT
|
|
Return a result that contains both successful items and a list
|
|
of errors. Caller decides what to do with each.
|
|
Used for: batch operations, multi-item fetches where one item
|
|
failing does not invalidate the rest.
|
|
"""
|
|
|
|
ABORT_ON_ERROR = ABORT_ON_ERROR
|
|
RETURN_DEFAULT = RETURN_DEFAULT
|
|
PARTIAL_RESULT = PARTIAL_RESULT
|
|
|
|
@classmethod
|
|
def doc(cls, pattern: str, *, since: str | None = None) -> str:
|
|
"""Return a docstring fragment describing the error pattern."""
|
|
desc = {
|
|
ABORT_ON_ERROR: "Raises exceptions on error. Router handles conversion to HTTP.",
|
|
RETURN_DEFAULT: "Returns empty result and logs warning on error. Never raises.",
|
|
PARTIAL_RESULT: "Returns (result, errors) tuple. Errors collected, not raised.",
|
|
}[pattern]
|
|
if since:
|
|
return f"{desc} (Since: {since})"
|
|
return desc
|