Debian Codegraph @

docs/usage/plugins/problem_details.rst

raw
1 ===============
2 Problem Details
3 ===============
4
5 .. versionadded:: 2.9.0
6
7 Problem details are a standardized way of providing machine-readable details of errors in HTTP
8 responses as specified in `RFC 9457`_, the latest RFC at the time of writing.
9
10 .. _RFC 9457: https://datatracker.ietf.org/doc/html/rfc9457
11
12 Usage
13 -----
14
15 To send a problem details response, the ``ProblemDetailsPlugin`` should be registered and then
16 a ``ProblemDetailsException`` can be raised anywhere which will automatically be converted
17 into a problem details response.
18
19 .. literalinclude:: /examples/plugins/problem_details/basic_usage.py
20 :language: python
21 :caption: Basic usage of the problem details plugin.
22
23 You can convert all ``HTTPExceptions`` into problem details response by enabling the flag in the ``ProblemDetailsConfig.``
24
25 .. literalinclude:: /examples/plugins/problem_details/convert_http_exceptions.py
26 :language: python
27 :caption: Converting ``HTTPException`` into problem details response.
28
29
30 You can also convert any exception that is not a ``HTTPException`` into a problem details response
31 by providing a mapping of the exception type to a callable that converts the exception into a
32 ``ProblemDetailsException.``
33
34 .. tip:: This can be used to override how the ``HTTPException`` is converted into a problem details response as well.
35
36 .. literalinclude:: /examples/plugins/problem_details/convert_exceptions.py
37 :language: python
38 :caption: Converting custom exceptions into problem details response.
39
40 .. warning:: If the ``extra`` field is a ``Mapping``, then it's merged into the problem details response, otherwise it's included in the response with the key ``extra``.