"""
The failure envelope that every typed Biblicus command prints when it fails.
A typed command is one that has a request model, a response model and a published schema in the
typed application programming interface. When such a command fails, the command-line interface
prints one :class:`CommandFailure` as JSON on standard output and exits with a status that
separates a rejected request from a failed operation.
"""
from __future__ import annotations
from typing import Any, Dict, Literal
from pydantic import BaseModel, ConfigDict, Field
INVALID_INPUT_EXIT_STATUS = 2
OPERATION_FAILED_EXIT_STATUS = 1
INVALID_INPUT_FAILURE_CODES = frozenset(
{
"invalid_input_json",
"missing_source_uri",
"missing_input",
"invalid_input",
"input_too_large",
"invalid_request",
"invalid_configuration",
}
)
OPERATION_FAILED_CODE = "operation_failed"
INVALID_REQUEST_CODE = "invalid_request"
[docs]
class InvalidRequestError(ValueError):
"""
A request failed validation before any operation ran.
The command-line interface reports it as the ``invalid_request`` failure with exit status 2.
"""
[docs]
class CommandFailureError(BaseModel):
"""
The error carried by a command failure.
:ivar code: Stable machine-readable failure code.
:vartype code: str
:ivar message: Human-readable explanation that never contains secrets or source text.
:vartype message: str
:ivar details: Optional structured diagnostics, empty when there are none.
:vartype details: dict[str, Any]
"""
model_config = ConfigDict(extra="forbid")
code: str = Field(min_length=1)
message: str = Field(min_length=1)
details: Dict[str, Any] = Field(default_factory=dict)
[docs]
class CommandFailure(BaseModel):
"""
The single JSON object a typed command prints on standard output when it fails.
:ivar status: Always ``failed``.
:vartype status: str
:ivar error: Code, message and details describing the failure.
:vartype error: CommandFailureError
"""
model_config = ConfigDict(extra="forbid")
status: Literal["failed"] = "failed"
error: CommandFailureError
@property
def exit_status(self) -> int:
"""
Exit status the command-line interface uses for this failure.
:return: ``2`` when the failure code names a rejected request, otherwise ``1``.
:rtype: int
"""
if self.error.code in INVALID_INPUT_FAILURE_CODES:
return INVALID_INPUT_EXIT_STATUS
return OPERATION_FAILED_EXIT_STATUS
[docs]
class CommandFailureException(Exception):
"""
Raised by a typed command to stop with a structured failure.
:ivar failure: The envelope the command-line interface prints.
:vartype failure: CommandFailure
"""
def __init__(self, *, code: str, message: str, details: Dict[str, Any] | None = None):
self.failure = CommandFailure(
error=CommandFailureError(code=code, message=message, details=dict(details or {}))
)
super().__init__(message)
[docs]
def raise_for_error_payload(
error_payload: Dict[str, Any], diagnostics: BaseModel | None = None
) -> None:
"""
Raise the structured failure described by a failed response model's ``error`` object.
:param error_payload: The ``error`` mapping of a failed response, with ``code``, ``message``
and optionally ``details``.
:type error_payload: dict[str, Any]
:param diagnostics: Typed diagnostics from the failed response, merged into ``details``
beneath any details the error already carries.
:type diagnostics: pydantic.BaseModel or None
:return: None.
:rtype: None
:raises CommandFailureException: Always, carrying the code, message and details.
"""
details: Dict[str, Any] = diagnostics.model_dump() if diagnostics is not None else {}
details.update(error_payload.get("details") or {})
raise CommandFailureException(
code=error_payload["code"], message=error_payload["message"], details=details
)