Navigation

The following classes and functions are designed to make working with
the WSGI specification easier or operate on the WSGI layer. All the
functionality from this module is available on the high-level
Request/Response classes.

The WSGI specification requires that all middlewares and gateways
respect the close callback of an iterator. Because it is useful to add
another close action to a returned iterator and adding a custom iterator
is a boring task this class can be used for that:

Wraps a stream so that it doesn’t read more than n bytes. If the
stream is exhausted and the caller tries to get more bytes from it
on_exhausted() is called which by default returns an empty
string. The return value of that function is forwarded
to the reader function. So if it returns an empty string
read() will return an empty string as well.

The limit however must never be higher than what the stream can
output. Otherwise readlines() will try to read past the
limit.

Note on WSGI compliance

calls to readline() and readlines() are not
WSGI compliant because it passes a size argument to the
readline methods. Unfortunately the WSGI PEP is not safely
implementable without a size argument to readline()
because there is no EOF marker in the stream. As a result
of that the use of readline() is discouraged.

Safely iterates line-based over an input stream. If the input stream
is not a LimitedStream the limit parameter is mandatory.

This uses the stream’s read() method internally as opposite
to the readline() method that is unsafe and can only be used
in violation of the WSGI specification. The same problem applies to the
__iter__ function of the input stream which calls readline()
without arguments.

If you need line-by-line processing it’s strongly recommended to iterate
over the input stream using this helper function.

Changed in version 0.8: This function now ensures that the limit was reached.

New in version 0.9: added support for iterators as input stream.

New in version 0.11.10: added support for the cap_at_buffer parameter.

Parameters:

stream – the stream or iterate to iterate over.

limit – the limit in bytes for the stream. (Usually
content length. Not necessary if the stream
is a LimitedStream.

buffer_size – The optional buffer size.

cap_at_buffer – if this is set chunks are split if they are longer
than the buffer size. Internally this is implemented
that the buffer size might be exhausted by a factor
of two however.

Wraps a file. This uses the WSGI server’s file wrapper if available
or otherwise the generic FileWrapper.

New in version 0.5.

If the file wrapper from the WSGI server is used it’s important to not
iterate over it from inside the application but to pass it through
unchanged. If you want to pass out a file wrapper inside a response
object you have to set direct_passthrough to True.

Return the real host for the given WSGI environment. This first checks
the X-Forwarded-Host header, then the normal Host header, and finally
the SERVER_NAME environment variable (using the first one it finds).

Optionally it verifies that the host is in a list of trusted hosts.
If the host is not in there it will raise a
SecurityError.

Returns the input stream from the WSGI environment and wraps it
in the most sensible way possible. The stream returned is not the
raw WSGI stream in most cases but one that is safe to read from
without taking into account the content length.

If content length is not set, the stream will be empty for safety reasons.
If the WSGI server supports chunked or infinite streams, it should set
the wsgi.input_terminated value in the WSGI environ to indicate that.

New in version 0.9.

Parameters:

environ – the WSGI environ to fetch the stream from.

safe_fallback – use an empty stream as a safe fallback when the
content length is not set. Disabling this allows infinite streams,
which can be a denial-of-service risk.

Returns the QUERY_STRING from the WSGI environment. This also takes
care about the WSGI decoding dance on Python 3 environments as a
native string. The string returned will be restricted to ASCII
characters.

Returns the SCRIPT_NAME from the WSGI environment and properly
decodes it. This also takes care about the WSGI decoding dance
on Python 3 environments. if the charset is set to None a
bytestring is returned.

New in version 0.9.

Parameters:

environ – the WSGI environment object to get the path from.

charset – the charset for the path, or None if no
decoding should be performed.

Returns the PATH_INFO from the WSGI environment and properly
decodes it. This also takes care about the WSGI decoding dance
on Python 3 environments. if the charset is set to None a
bytestring is returned.

New in version 0.9.

Parameters:

environ – the WSGI environment object to get the path from.

charset – the charset for the path info, or None if no
decoding should be performed.