Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/werkzeug/wsgi.py: 22%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from __future__ import annotations
3import io
4import typing as t
5from functools import partial
6from functools import update_wrapper
8from .exceptions import ClientDisconnected
9from .exceptions import RequestEntityTooLarge
10from .sansio import utils as _sansio_utils
11from .sansio.utils import host_is_trusted # noqa: F401 # Imported as part of API
13if t.TYPE_CHECKING:
14 from _typeshed.wsgi import WSGIApplication
15 from _typeshed.wsgi import WSGIEnvironment
18def responder(f: t.Callable[..., WSGIApplication]) -> WSGIApplication:
19 """Marks a function as responder. Decorate a function with it and it
20 will automatically call the return value as WSGI application.
22 Example::
24 @responder
25 def application(environ, start_response):
26 return Response('Hello World!')
27 """
28 return update_wrapper(lambda *a: f(*a)(*a[-2:]), f)
31def get_current_url(
32 environ: WSGIEnvironment,
33 root_only: bool = False,
34 strip_querystring: bool = False,
35 host_only: bool = False,
36 trusted_hosts: t.Iterable[str] | None = None,
37) -> str:
38 """Recreate the URL for a request from the parts in a WSGI
39 environment.
41 The URL is an IRI, not a URI, so it may contain Unicode characters.
42 Use :func:`~werkzeug.urls.iri_to_uri` to convert it to ASCII.
44 :param environ: The WSGI environment to get the URL parts from.
45 :param root_only: Only build the root path, don't include the
46 remaining path or query string.
47 :param strip_querystring: Don't include the query string.
48 :param host_only: Only build the scheme and host.
49 :param trusted_hosts: A list of trusted host names to validate the
50 host against.
51 """
52 parts = {
53 "scheme": environ["wsgi.url_scheme"],
54 "host": get_host(environ, trusted_hosts),
55 }
57 if not host_only:
58 parts["root_path"] = environ.get("SCRIPT_NAME", "")
60 if not root_only:
61 parts["path"] = environ.get("PATH_INFO", "")
63 if not strip_querystring:
64 parts["query_string"] = environ.get("QUERY_STRING", "").encode("latin1")
66 return _sansio_utils.get_current_url(**parts)
69def _get_server(
70 environ: WSGIEnvironment,
71) -> tuple[str, int | None] | None:
72 name = environ.get("SERVER_NAME")
74 if name is None:
75 return None
77 try:
78 port: int | None = int(environ.get("SERVER_PORT", None))
79 except (TypeError, ValueError):
80 # unix socket
81 port = None
83 return name, port
86def get_host(
87 environ: WSGIEnvironment, trusted_hosts: t.Iterable[str] | None = None
88) -> str:
89 """Return the host for the given WSGI environment.
91 The ``Host`` header is preferred, then ``SERVER_NAME`` if it's not
92 set. The returned host will only contain the port if it is different
93 than the standard port for the protocol.
95 Optionally, verify that the host is trusted using
96 :func:`host_is_trusted` and raise a
97 :exc:`~werkzeug.exceptions.SecurityError` if it is not.
99 :param environ: A WSGI environment dict.
100 :param trusted_hosts: A list of trusted host names.
102 :return: Host, with port if necessary.
103 :raise ~werkzeug.exceptions.SecurityError: If the host is not
104 trusted.
105 """
106 return _sansio_utils.get_host(
107 environ["wsgi.url_scheme"],
108 environ.get("HTTP_HOST"),
109 _get_server(environ),
110 trusted_hosts,
111 )
114def get_content_length(environ: WSGIEnvironment) -> int | None:
115 """Return the ``Content-Length`` header value as an int. If the header is not given
116 or the ``Transfer-Encoding`` header is ``chunked``, ``None`` is returned to indicate
117 a streaming request. If the value is not an integer, or negative, 0 is returned.
119 :param environ: The WSGI environ to get the content length from.
121 .. versionadded:: 0.9
122 """
123 return _sansio_utils.get_content_length(
124 http_content_length=environ.get("CONTENT_LENGTH"),
125 http_transfer_encoding=environ.get("HTTP_TRANSFER_ENCODING"),
126 )
129def get_input_stream(
130 environ: WSGIEnvironment,
131 safe_fallback: bool = True,
132 max_content_length: int | None = None,
133) -> t.IO[bytes]:
134 """Return the WSGI input stream, wrapped so that it may be read safely without going
135 past the ``Content-Length`` header value or ``max_content_length``.
137 If ``Content-Length`` exceeds ``max_content_length``, a
138 :exc:`RequestEntityTooLarge`` ``413 Content Too Large`` error is raised.
140 If the WSGI server sets ``environ["wsgi.input_terminated"]``, it indicates that the
141 server handles terminating the stream, so it is safe to read directly. For example,
142 a server that knows how to handle chunked requests safely would set this.
144 If ``max_content_length`` is set, it can be enforced on streams if
145 ``wsgi.input_terminated`` is set. Otherwise, an empty stream is returned unless the
146 user explicitly disables this safe fallback.
148 If the limit is reached before the underlying stream is exhausted (such as a file
149 that is too large, or an infinite stream), the remaining contents of the stream
150 cannot be read safely. Depending on how the server handles this, clients may show a
151 "connection reset" failure instead of seeing the 413 response.
153 :param environ: The WSGI environ containing the stream.
154 :param safe_fallback: Return an empty stream when ``Content-Length`` is not set.
155 Disabling this allows infinite streams, which can be a denial-of-service risk.
156 :param max_content_length: The maximum length that content-length or streaming
157 requests may not exceed.
159 .. versionchanged:: 2.3.2
160 ``max_content_length`` is only applied to streaming requests if the server sets
161 ``wsgi.input_terminated``.
163 .. versionchanged:: 2.3
164 Check ``max_content_length`` and raise an error if it is exceeded.
166 .. versionadded:: 0.9
167 """
168 stream = t.cast(t.IO[bytes], environ["wsgi.input"])
169 content_length = get_content_length(environ)
171 if content_length is not None and max_content_length is not None:
172 if content_length > max_content_length:
173 raise RequestEntityTooLarge()
175 # A WSGI server can set this to indicate that it terminates the input stream. In
176 # that case the stream is safe without wrapping, or can enforce a max length.
177 if "wsgi.input_terminated" in environ:
178 if max_content_length is not None:
179 # If this is moved above, it can cause the stream to hang if a read attempt
180 # is made when the client sends no data. For example, the development server
181 # does not handle buffering except for chunked encoding.
182 return t.cast(
183 t.IO[bytes], LimitedStream(stream, max_content_length, is_max=True)
184 )
186 return stream
188 # No limit given, return an empty stream unless the user explicitly allows the
189 # potentially infinite stream. An infinite stream is dangerous if it's not expected,
190 # as it can tie up a worker indefinitely.
191 if content_length is None:
192 return io.BytesIO() if safe_fallback else stream
194 return t.cast(t.IO[bytes], LimitedStream(stream, content_length))
197def get_path_info(environ: WSGIEnvironment) -> str:
198 """Return ``PATH_INFO`` from the WSGI environment.
200 :param environ: WSGI environment to get the path from.
202 .. versionchanged:: 3.0
203 The ``charset`` and ``errors`` parameters were removed.
205 .. versionadded:: 0.9
206 """
207 path: bytes = environ.get("PATH_INFO", "").encode("latin1")
208 return path.decode(errors="replace")
211class ClosingIterator:
212 """The WSGI specification requires that all middlewares and gateways
213 respect the `close` callback of the iterable returned by the application.
214 Because it is useful to add another close action to a returned iterable
215 and adding a custom iterable is a boring task this class can be used for
216 that::
218 return ClosingIterator(app(environ, start_response), [cleanup_session,
219 cleanup_locals])
221 If there is just one close function it can be passed instead of the list.
223 A closing iterator is not needed if the application uses response objects
224 and finishes the processing if the response is started::
226 try:
227 return response(environ, start_response)
228 finally:
229 cleanup_session()
230 cleanup_locals()
231 """
233 def __init__(
234 self,
235 iterable: t.Iterable[bytes],
236 callbacks: None
237 | (t.Callable[[], None] | t.Iterable[t.Callable[[], None]]) = None,
238 ) -> None:
239 iterator = iter(iterable)
240 self._next = t.cast(t.Callable[[], bytes], partial(next, iterator))
241 if callbacks is None:
242 callbacks = []
243 elif callable(callbacks):
244 callbacks = [callbacks]
245 else:
246 callbacks = list(callbacks)
247 iterable_close = getattr(iterable, "close", None)
248 if iterable_close:
249 callbacks.insert(0, iterable_close)
250 self._callbacks = callbacks
252 def __iter__(self) -> ClosingIterator:
253 return self
255 def __next__(self) -> bytes:
256 return self._next()
258 def close(self) -> None:
259 for callback in self._callbacks:
260 callback()
263def wrap_file(
264 environ: WSGIEnvironment, file: t.IO[bytes], buffer_size: int = 8192
265) -> t.Iterable[bytes]:
266 """Wraps a file. This uses the WSGI server's file wrapper if available
267 or otherwise the generic :class:`FileWrapper`.
269 .. versionadded:: 0.5
271 If the file wrapper from the WSGI server is used it's important to not
272 iterate over it from inside the application but to pass it through
273 unchanged. If you want to pass out a file wrapper inside a response
274 object you have to set :attr:`Response.direct_passthrough` to `True`.
276 More information about file wrappers are available in :pep:`333`.
278 :param file: a :class:`file`-like object with a :meth:`~file.read` method.
279 :param buffer_size: number of bytes for one iteration.
280 """
281 return environ.get("wsgi.file_wrapper", FileWrapper)( # type: ignore
282 file, buffer_size
283 )
286class FileWrapper:
287 """This class can be used to convert a :class:`file`-like object into
288 an iterable. It yields `buffer_size` blocks until the file is fully
289 read.
291 You should not use this class directly but rather use the
292 :func:`wrap_file` function that uses the WSGI server's file wrapper
293 support if it's available.
295 .. versionadded:: 0.5
297 If you're using this object together with a :class:`Response` you have
298 to use the `direct_passthrough` mode.
300 :param file: a :class:`file`-like object with a :meth:`~file.read` method.
301 :param buffer_size: number of bytes for one iteration.
302 """
304 def __init__(self, file: t.IO[bytes], buffer_size: int = 8192) -> None:
305 self.file = file
306 self.buffer_size = buffer_size
308 def close(self) -> None:
309 if hasattr(self.file, "close"):
310 self.file.close()
312 def seekable(self) -> bool:
313 if hasattr(self.file, "seekable"):
314 return self.file.seekable()
315 if hasattr(self.file, "seek"):
316 return True
317 return False
319 def seek(self, *args: t.Any) -> None:
320 if hasattr(self.file, "seek"):
321 self.file.seek(*args)
323 def tell(self) -> int | None:
324 if hasattr(self.file, "tell"):
325 return self.file.tell()
326 return None
328 def __iter__(self) -> FileWrapper:
329 return self
331 def __next__(self) -> bytes:
332 data = self.file.read(self.buffer_size)
333 if data:
334 return data
335 raise StopIteration()
338class _RangeWrapper:
339 # private for now, but should we make it public in the future ?
341 """This class can be used to convert an iterable object into
342 an iterable that will only yield a piece of the underlying content.
343 It yields blocks until the underlying stream range is fully read.
344 The yielded blocks will have a size that can't exceed the original
345 iterator defined block size, but that can be smaller.
347 If you're using this object together with a :class:`Response` you have
348 to use the `direct_passthrough` mode.
350 :param iterable: an iterable object with a :meth:`__next__` method.
351 :param start_byte: byte from which read will start.
352 :param byte_range: how many bytes to read.
353 """
355 def __init__(
356 self,
357 iterable: t.Iterable[bytes] | t.IO[bytes],
358 start_byte: int = 0,
359 byte_range: int | None = None,
360 ):
361 self.iterable = iter(iterable)
362 self.byte_range = byte_range
363 self.start_byte = start_byte
364 self.end_byte = None
366 if byte_range is not None:
367 self.end_byte = start_byte + byte_range
369 self.read_length = 0
370 self.seekable = hasattr(iterable, "seekable") and iterable.seekable()
371 self.end_reached = False
373 def __iter__(self) -> _RangeWrapper:
374 return self
376 def _next_chunk(self) -> bytes:
377 try:
378 chunk = next(self.iterable)
379 self.read_length += len(chunk)
380 return chunk
381 except StopIteration:
382 self.end_reached = True
383 raise
385 def _first_iteration(self) -> tuple[bytes | None, int]:
386 chunk = None
387 if self.seekable:
388 self.iterable.seek(self.start_byte) # type: ignore
389 self.read_length = self.iterable.tell() # type: ignore
390 contextual_read_length = self.read_length
391 else:
392 while self.read_length <= self.start_byte:
393 chunk = self._next_chunk()
394 if chunk is not None:
395 chunk = chunk[self.start_byte - self.read_length :]
396 contextual_read_length = self.start_byte
397 return chunk, contextual_read_length
399 def _next(self) -> bytes:
400 if self.end_reached:
401 raise StopIteration()
402 chunk = None
403 contextual_read_length = self.read_length
404 if self.read_length == 0:
405 chunk, contextual_read_length = self._first_iteration()
406 if chunk is None:
407 chunk = self._next_chunk()
408 if self.end_byte is not None and self.read_length >= self.end_byte:
409 self.end_reached = True
410 return chunk[: self.end_byte - contextual_read_length]
411 return chunk
413 def __next__(self) -> bytes:
414 chunk = self._next()
415 if chunk:
416 return chunk
417 self.end_reached = True
418 raise StopIteration()
420 def close(self) -> None:
421 if hasattr(self.iterable, "close"):
422 self.iterable.close()
425class LimitedStream(io.RawIOBase):
426 """Wrap a stream so that it doesn't read more than a given limit. This is used to
427 limit ``wsgi.input`` to the ``Content-Length`` header value or
428 :attr:`.Request.max_content_length`.
430 When attempting to read after the limit has been reached, :meth:`on_exhausted` is
431 called. When the limit is a maximum, this raises :exc:`.RequestEntityTooLarge`.
433 If reading from the stream returns zero bytes or raises an error,
434 :meth:`on_disconnect` is called, which raises :exc:`.ClientDisconnected`. When the
435 limit is a maximum and zero bytes were read, no error is raised, since it may be the
436 end of the stream.
438 If the limit is reached before the underlying stream is exhausted (such as a file
439 that is too large, or an infinite stream), the remaining contents of the stream
440 cannot be read safely. Depending on how the server handles this, clients may show a
441 "connection reset" failure instead of seeing the 413 response.
443 :param stream: The stream to read from. Must be a readable binary IO object.
444 :param limit: The limit in bytes to not read past. Should be either the
445 ``Content-Length`` header value or ``request.max_content_length``.
446 :param is_max: Whether the given ``limit`` is ``request.max_content_length`` instead
447 of the ``Content-Length`` header value. This changes how exhausted and
448 disconnect events are handled.
450 .. versionchanged:: 2.3
451 Handle ``max_content_length`` differently than ``Content-Length``.
453 .. versionchanged:: 2.3
454 Implements ``io.RawIOBase`` rather than ``io.IOBase``.
455 """
457 def __init__(self, stream: t.IO[bytes], limit: int, is_max: bool = False) -> None:
458 self._stream = stream
459 self._pos = 0
460 self.limit = limit
461 self._limit_is_max = is_max
463 @property
464 def is_exhausted(self) -> bool:
465 """Whether the current stream position has reached the limit."""
466 return self._pos >= self.limit
468 def on_exhausted(self) -> None:
469 """Called when attempting to read after the limit has been reached.
471 The default behavior is to do nothing, unless the limit is a maximum, in which
472 case it raises :exc:`.RequestEntityTooLarge`.
474 .. versionchanged:: 2.3
475 Raises ``RequestEntityTooLarge`` if the limit is a maximum.
477 .. versionchanged:: 2.3
478 Any return value is ignored.
479 """
480 if self._limit_is_max:
481 raise RequestEntityTooLarge()
483 def on_disconnect(self, error: Exception | None = None) -> None:
484 """Called when an attempted read receives zero bytes before the limit was
485 reached. This indicates that the client disconnected before sending the full
486 request body.
488 The default behavior is to raise :exc:`.ClientDisconnected`, unless the limit is
489 a maximum and no error was raised.
491 .. versionchanged:: 2.3
492 Added the ``error`` parameter. Do nothing if the limit is a maximum and no
493 error was raised.
495 .. versionchanged:: 2.3
496 Any return value is ignored.
497 """
498 if not self._limit_is_max or error is not None:
499 raise ClientDisconnected()
501 # If the limit is a maximum, then we may have read zero bytes because the
502 # streaming body is complete. There's no way to distinguish that from the
503 # client disconnecting early.
505 def exhaust(self) -> bytes:
506 """Exhaust the stream by reading until the limit is reached or the client
507 disconnects, returning the remaining data.
509 .. versionchanged:: 2.3
510 Return the remaining data.
512 .. versionchanged:: 2.2.3
513 Handle case where wrapped stream returns fewer bytes than requested.
514 """
515 if not self.is_exhausted:
516 return self.readall()
518 return b""
520 def readinto(self, b: bytearray) -> int | None: # type: ignore[override]
521 size = len(b)
522 remaining = self.limit - self._pos
524 if remaining <= 0:
525 self.on_exhausted()
526 return 0
528 if hasattr(self._stream, "readinto"):
529 # Use stream.readinto if it's available.
530 if size <= remaining:
531 # The size fits in the remaining limit, use the buffer directly.
532 try:
533 out_size: int | None = self._stream.readinto(b)
534 except (OSError, ValueError) as e:
535 self.on_disconnect(error=e)
536 return 0
537 else:
538 # Use a temp buffer with the remaining limit as the size.
539 temp_b = bytearray(remaining)
541 try:
542 out_size = self._stream.readinto(temp_b)
543 except (OSError, ValueError) as e:
544 self.on_disconnect(error=e)
545 return 0
547 if out_size:
548 b[:out_size] = temp_b
549 else:
550 # WSGI requires that stream.read is available.
551 try:
552 data = self._stream.read(min(size, remaining))
553 except (OSError, ValueError) as e:
554 self.on_disconnect(error=e)
555 return 0
557 out_size = len(data)
558 b[:out_size] = data
560 if not out_size:
561 # Read zero bytes from the stream.
562 self.on_disconnect()
563 return 0
565 self._pos += out_size
566 return out_size
568 def readall(self) -> bytes:
569 if self.is_exhausted:
570 self.on_exhausted()
571 return b""
573 out = bytearray()
575 # The parent implementation uses "while True", which results in an extra read.
576 while not self.is_exhausted:
577 data = self.read(1024 * 64)
579 # Stream may return empty before a max limit is reached.
580 if not data:
581 break
583 out.extend(data)
585 return bytes(out)
587 def tell(self) -> int:
588 """Return the current stream position.
590 .. versionadded:: 0.9
591 """
592 return self._pos
594 def readable(self) -> bool:
595 return True