Debian Codegraph @

docs/usage/requests.rst

raw
1 Requests
2 ========
3
4 Request body
5 ------------
6
7 The body of HTTP requests can be accessed using the special ``data`` parameter in a handler function.
8
9 .. literalinclude:: /examples/request_data/request_data_1.py
10 :language: python
11
12
13 The type of ``data`` can be any supported type, including
14
15
16 * Arbitrary stdlib types
17 * :class:`TypedDicts <typing.TypedDict>`
18 * :func:`dataclasses <dataclasses.dataclass>`
19 * Types supported via :doc:`plugins </usage/plugins/index>` ie.
20 - `Msgspec Struct <https://msgspec.devstructs.html>`_
21 - `Pydantic models <https://docs.pydantic.dev/usage/models/>`_
22 - `Attrs classes <https://www.attrs.org/en/stable/>`_
23
24
25 .. literalinclude:: /examples/request_data/request_data_2.py
26 :language: python
27
28
29 Validation and customization of OpenAPI documentation
30 -----------------------------------------------------
31
32 With the help of :class:`Body <litestar.params.Body>`, you have fine-grained control over the validation
33 of the request body, and can also customize the OpenAPI documentation:
34
35
36 .. tab-set::
37
38 .. tab-item:: example
39
40 .. literalinclude:: /examples/request_data/request_data_3.py
41 :language: python
42
43 .. tab-item:: how to test
44
45 .. literalinclude:: ../../tests/examples/test_request_data.py
46 :language: python
47 :lines: 35-41
48
49
50 Content-type
51 ------------
52
53 By default, Litestar will try to parse the request body as JSON. While this may be desired
54 in most cases, you might want to specify a different type. You can do so by passing a
55 :class:`RequestEncodingType <litestar.enums.RequestEncodingType>` to ``Body``. This will also
56 help to generate the correct media-type in the OpenAPI schema.
57
58 URL Encoded Form Data
59 ^^^^^^^^^^^^^^^^^^^^^
60
61 To access data sent as `url-encoded form data <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST>`_,
62 i.e. ``application/x-www-form-urlencoded`` Content-Type header, wrap the ``data``
63 annotation with :data:`~litestar.params.URLEncodedBody`:
64
65 .. tab-set::
66
67 .. tab-item:: example
68
69 .. literalinclude:: /examples/request_data/request_data_4.py
70 :language: python
71
72 .. tab-item:: how to test
73
74 .. literalinclude:: ../../tests/examples/test_request_data.py
75 :language: python
76 :lines: 44-48
77
78 .. note::
79
80 URL encoded data is inherently less versatile than JSON data - for example, it cannot handle complex
81 dictionaries and deeply nested data. It should only be used for simple data structures.
82
83
84 .. tip::
85 ``URLEncodedBody[<type>]`` is a shorthand for
86 ``Annotated[<type>, Body(media_type=RequestEncodingType.URL_ENCODED)]``. If you want
87 to pass additional OpenAPI metadata or constraints, use the
88 :class:`~typing.Annotated` form
89
90
91 MultiPart Form Data
92 ^^^^^^^^^^^^^^^^^^^
93
94 You can access data uploaded using a request with a
95 `multipart/form-data <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST>`_
96 Content-Type header by specifying the data with :data:`~litestar.params.MultipartBody`:
97
98 .. tab-set::
99
100 .. tab-item:: example
101
102 .. literalinclude:: /examples/request_data/request_data_5.py
103 :language: python
104
105 .. tab-item:: how to test
106
107 .. literalinclude:: ../../tests/examples/test_request_data.py
108 :language: python
109 :lines: 51-64
110
111
112 .. tip::
113 ``MultipartBody[<type>]`` is a shorthand for
114 ``Annotated[<type>, Body(media_type=RequestEncodingType.MULTI_PART)]``. If you want
115 to pass additional OpenAPI metadata or constraints, use the
116 :class:`~typing.Annotated` form
117
118
119 File uploads
120 ------------
121
122 In case of files uploaded, Litestar transforms the results into an instance
123 of :class:`UploadFile <.datastructures.upload_file.UploadFile>` class, which offer a convenient
124 interface for working with files. Therefore, you need to type your file uploads accordingly.
125
126 To access a single file simply type ``data`` as :class:`UploadFile <.datastructures.upload_file.UploadFile>`:
127
128
129 .. tab-set::
130
131 .. tab-item:: Async
132
133 .. tab-set::
134
135 .. tab-item:: example
136
137 .. literalinclude:: /examples/request_data/request_data_6.py
138 :language: python
139
140 .. tab-item:: how to test
141
142 .. literalinclude:: ../../tests/examples/test_request_data.py
143 :language: python
144 :lines: 67-71
145
146 .. tab-item:: Sync
147
148 .. tab-set::
149
150 .. tab-item:: example
151
152 .. literalinclude:: /examples/request_data/request_data_7.py
153 :language: python
154
155 .. tab-item:: how to test
156
157 .. literalinclude:: ../../tests/examples/test_request_data.py
158 :language: python
159 :lines: 74-78
160
161 .. admonition:: Technical details
162 :class: info
163
164 :class:`UploadFile <.datastructures.UploadFile>` wraps
165 :class:`SpooledTemporaryFile <tempfile.SpooledTemporaryFile>` so it can be used asynchronously. Inside a synchronous
166 function we don't need this wrapper, so we can use its :meth:`read <io.TextIOBase.read>` method directly.
167
168
169
170 Multiple files
171 ^^^^^^^^^^^^^^
172
173 To access multiple files with known filenames, you can use any structured type:
174
175
176 .. tab-set::
177
178 .. tab-item:: example
179
180 .. literalinclude:: /examples/request_data/request_data_8.py
181 :language: python
182
183 .. tab-item:: how to test
184
185 .. literalinclude:: ../../tests/examples/test_request_data.py
186 :language: python
187 :lines: 81-87
188
189
190 Files as a dictionary
191 ^^^^^^^^^^^^^^^^^^^^^
192
193 If you do not care about parsing and validation and only want to access the form data as a dictionary, you can use a ``dict`` instead:
194
195 .. tab-set::
196
197 .. tab-item:: example
198
199 .. literalinclude:: /examples/request_data/request_data_9.py
200 :language: python
201
202 .. tab-item:: how to test
203
204 .. literalinclude:: ../../tests/examples/test_request_data.py
205 :language: python
206 :lines: 90-97
207
208
209 Files as a list
210 ^^^^^^^^^^^^^^^
211
212 Finally, you can also access the files as a list without the filenames:
213
214 .. tab-set::
215
216 .. tab-item:: example
217
218 .. literalinclude:: /examples/request_data/request_data_10.py
219 :language: python
220
221 .. tab-item:: how to test
222
223 .. literalinclude:: ../../tests/examples/test_request_data.py
224 :language: python
225 :lines: 100-133
226
227 MessagePack data
228 ----------------
229
230 To receive `MessagePack <https://msgpack.org/>`_ data, annotate ``data`` with
231 :data:`~litestar.params.MsgPackBody`:
232
233 .. tab-set::
234
235 .. tab-item:: example
236
237 .. literalinclude:: /examples/request_data/msgpack_request.py
238 :language: python
239
240 .. tab-item:: how to test
241
242 .. literalinclude:: ../../tests/examples/test_request_data.py
243 :language: python
244 :lines: 136-141
245
246 .. tip::
247 ``MsgPackBody[<type>]`` is a shorthand for
248 ``Annotated[<type>, Body(media_type=RequestEncodingType.MESSAGEPACK)]``. If you want
249 to pass additional OpenAPI metadata or constraints, use the
250 :class:`~typing.Annotated` form
251
252
253
254 Custom Request
255 --------------
256
257 .. versionadded:: 2.7.0
258
259 Litestar supports custom ``request_class`` instances, which can be used to further configure the default :class:`Request`.
260 The example below illustrates how to implement custom request class for the whole application.
261
262 .. dropdown:: Example of a custom request at the application level
263
264 .. tab-set::
265
266 .. tab-item:: example
267
268 .. literalinclude:: /examples/request_data/custom_request.py
269 :language: python
270
271 .. tab-item:: how to test
272
273 .. literalinclude:: ../../tests/examples/test_request_data.py
274 :language: python
275 :lines: 144-147
276
277 .. admonition:: Layered architecture
278
279 Request classes are part of Litestar's layered architecture, which means you can
280 set a request class on every layer of the application. If you have set a request
281 class on multiple layers, the layer closest to the route handler will take precedence.
282
283 You can read more about this in the :ref:`usage/applications:layered architecture` section
284
285
286 Limits
287 -------
288
289 Body size
290 ^^^^^^^^^^
291
292 A limit for the allowed request body size can be set on all layers via the
293 ``request_max_body_size`` parameter and defaults to 10MB. If a request body exceeds this
294 limit, a ``413 - Request Entity Too Large``
295 response will be returned. This limit applies to all methods of consuming the request
296 body, including requesting it via the ``body`` parameter in a route handler and
297 consuming it through a manually constructed :class:`~litestar.connection.Request`
298 instance, e.g. in a middleware.
299
300 To disable this limit for a specific handler / router / controller, it can be set to
301 :obj:`None`.
302
303 .. danger::
304 Setting ``request_max_body_size=None`` is strongly discouraged as it exposes the
305 application to a denial of service (DoS) attack by sending arbitrarily large
306 request bodies to the affected endpoint. Because Litestar has to read the whole body
307 to perform certain actions, such as parsing JSON, it will fill up all the available
308 memory / swap until the application / server crashes, should no outside limits be
309 imposed.
310
311 This is generally only recommended in environments where the application is running
312 behind a reverse proxy such as NGINX, where a size limit is already set.
313
314
315 .. danger::
316 Since ``request_max_body_size`` is handled on a per-request basis, it won't affect
317 middlewares or ASGI handlers when they try to access the request body via the raw
318 ASGI events. To avoid this, middlewares and ASGI handlers should construct a
319 :class:`~litestar.connection.Request` instance and use the regular
320 :meth:`~litestar.connection.Request.stream` /
321 :meth:`~litestar.connection.Request.body` or content-appropriate method to consume
322 the request body in a safe manner.
323
324
325 .. tip::
326 For requests that define a ``Content-Length`` header, Litestar will not attempt to
327 read the request body should the header value exceed the ``request_max_body_size``.
328
329 Validation that the actual request body matches the ``Content-Length`` header is
330 delegated to the ASGI server (e.g. uvicorn). This ensures compatibility with
331 request decompression middleware, where the decompressed body may legitimately
332 exceed the wire-format ``Content-Length``.