labthings_fastapi.problem_details

JSON representations of errors as per RFC 9457.

This module defines a model and supporting functions that help to create “Problem Details” objects to represent errors in HTTP responses.

Attributes

DOCS_URL
PYTHON_DOCS_URL
Params
ReturnT

Classes

ProblemDetails

A model to describe an error that occurred in an invocation.

Functions

docs_url(→ str | None)	Return a URL identifying a LabThings exception.
exceptions_to_problem_details(...)	Decorate a function to handle errors with a ProblemDetails response.

Module Contents

class labthings_fastapi.problem_details.ProblemDetails(/, **data: Any)

Bases: pydantic.BaseModel

A model to describe an error that occurred in an invocation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

detail: str | None = None

A human-readable string with details of the error.

type: str | None = None

A URI giving a unique reference for the error.

status: int | None = None

An HTTP status code describing the error.

title: str | None = None

A human-readable title for the error.

instance: str | None = None

A URI that may or may not give details about this specific instance.

classmethod from_exception(exc: BaseException) → Self

Generate a ProblemDetails model from an exception instance.

Parameters:

exc – the exception instance to be described.

Returns:

a ProblemDetails object describing exc.

json_response() → fastapi.Response

Return a JSONResponse representing this object.

Returns:

a JSONResponse object suitable for returning from a request handler.

labthings_fastapi.problem_details.DOCS_URL = 'https://labthings-fastapi.readthedocs.io/en/latest/autoapi/labthings_fastapi/exceptions/index.html'

labthings_fastapi.problem_details.PYTHON_DOCS_URL = 'https://docs.python.org/3/library/exceptions.html'

labthings_fastapi.problem_details.docs_url(exc: type[BaseException]) → str | None

Return a URL identifying a LabThings exception.

Parameters:

exc – An exception class.

Returns:

a URL pointing to that exception in the docs, or None if the exception is not in this module.

labthings_fastapi.problem_details.Params

labthings_fastapi.problem_details.ReturnT

labthings_fastapi.problem_details.exceptions_to_problem_details(logger: logging.Logger | None) → Callable[[Callable[Params, ReturnT]], Callable[Params, ReturnT]]

Decorate a function to handle errors with a ProblemDetails response.

Parameters:

logger – the logger to use, or None for no logging.

Returns:

a decorator that handles errors by returning a ProblemDetails object.