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.
Iterator / Stream Helpers
These classes and functions simplify working with the WSGI application iterator and the input stream.
class werkzeug.wsgi.ClosingIterator(iterable, callbacks=None)
The WSGI specification requires that all middlewares and gateways respect the [UNKNOWN NODE title_reference] 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:
return ClosingIterator(app(environ, start_response), [cleanup_session,
cleanup_locals])
If there is just one close function it can be passed instead of the list.
A closing iterator is not needed if the application uses response objects and finishes the processing if the response is started:
try:
return response(environ, start_response)
finally:
cleanup_session()
cleanup_locals()
class werkzeug.wsgi.FileWrapper(file, buffer_size=8192)
This class can be used to convert a file
-like object into
an iterable. It yields [UNKNOWN NODE title_reference] blocks until the file is fully
read.
You should not use this class directly but rather use the
wrap_file()
function that uses the WSGI server’s file wrapper
support if it’s available.
New in version 0.5.
If you’re using this object together with a BaseResponse
you have
to use the [UNKNOWN NODE title_reference] mode.
- file – a
file
-like object with aread()
method. - buffer_size – number of bytes for one iteration.
class werkzeug.wsgi.LimitedStream(stream, limit)
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.
For the same reason iterating over the LimitedStream
is not portable. It internally calls readline()
.
We strongly suggest using read()
only or using the
make_line_iter()
which safely iterates line-based
over a WSGI input stream.
- stream – the stream to wrap.
- limit – the limit for the stream, must not be longer than what the string can provide if the stream does not end with [UNKNOWN NODE title_reference] (like [UNKNOWN NODE title_reference])
exhaust(chunk_size=65536)
Exhaust the stream. This consumes all the data left until the limit is reached.
is_exhausted
If the stream is exhausted this attribute is [UNKNOWN NODE title_reference].
on_disconnect()
What should happen if a disconnect is detected? The return
value of this function is returned from read functions in case
the client went away. By default a
ClientDisconnected
exception is raised.
on_exhausted()
This is called when the stream tries to read past the limit. The return value of this function is returned from the reading function.
read(size=None)
Read [UNKNOWN NODE title_reference] bytes or if size is not provided everything is read.
readable()
Return whether object was opened for reading.
If False, read() will raise IOError.
readline(size=None)
Reads one line from the stream.
readlines(size=None)
Reads a file into a list of strings. It calls readline()
until the file is read to the end. It does support the optional
[UNKNOWN NODE title_reference] argument if the underlaying stream supports it for
[UNKNOWN NODE title_reference].
tell()
Returns the position of the stream.
New in version 0.9.
werkzeug.wsgi.make_line_iter(stream, limit=None, buffer_size=10240, cap_at_buffer=False)
Safely iterates line-based over an input stream. If the input stream
is not a LimitedStream
the [UNKNOWN NODE title_reference] 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
[UNKNOWN NODE title_reference] 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 [UNKNOWN NODE title_reference] parameter.
- stream – the stream or iterate to iterate over.
- limit – the limit in bytes for the stream. (Usually
content length. Not necessary if the [UNKNOWN NODE title_reference]
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.
werkzeug.wsgi.make_chunk_iter(stream, separator, limit=None, buffer_size=10240, cap_at_buffer=False)
Works like make_line_iter()
but accepts a separator
which divides chunks. If you want newline based processing
you should use make_line_iter()
instead as it
supports arbitrary newline markers.
New in version 0.8.
New in version 0.9: added support for iterators as input stream.
New in version 0.11.10: added support for the [UNKNOWN NODE title_reference] parameter.
- stream – the stream or iterate to iterate over.
- separator – the separator that divides chunks.
- limit – the limit in bytes for the stream. (Usually content length. Not necessary if the [UNKNOWN NODE title_reference] is otherwise already limited).
- 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.
werkzeug.wsgi.wrap_file(environ, file, buffer_size=8192)
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 [UNKNOWN NODE title_reference].
More information about file wrappers are available in PEP 333.
- file – a
file
-like object with aread()
method. - buffer_size – number of bytes for one iteration.
Environ Helpers
These functions operate on the WSGI environment. They extract useful information or perform common manipulations:
werkzeug.wsgi.get_host(environ, trusted_hosts=None)
Return the real host for the given WSGI environment. This first checks the [UNKNOWN NODE title_reference] header, then the normal [UNKNOWN NODE title_reference] header, and finally the [UNKNOWN NODE title_reference] 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
.
- environ – the WSGI environment to get the host of.
- trusted_hosts – a list of trusted hosts, see
host_is_trusted()
for more information.
werkzeug.wsgi.get_content_length(environ)
Returns the content length from the WSGI environment as
integer. If it’s not available or chunked transfer encoding is used,
None
is returned.
New in version 0.9.
werkzeug.wsgi.get_input_stream(environ, safe_fallback=True)
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.
- 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.
werkzeug.wsgi.get_current_url(environ, root_only=False, strip_querystring=False, host_only=False, trusted_hosts=None)
A handy helper function that recreates the full URL as IRI for the current request or parts of it. Here’s an example:
[UNKNOWN NODE doctest_block]This 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
.
Note that the string returned might contain unicode characters as the
representation is an IRI not an URI. If you need an ASCII only
representation you can use the iri_to_uri()
function:
- environ – the WSGI environment to get the current URL from.
- root_only – set [UNKNOWN NODE title_reference] if you only want the root URL.
- strip_querystring – set to [UNKNOWN NODE title_reference] if you don’t want the querystring.
- host_only – set to [UNKNOWN NODE title_reference] if the host URL should be returned.
- trusted_hosts – a list of trusted hosts, see
host_is_trusted()
for more information.
werkzeug.wsgi.get_query_string(environ)
Returns the [UNKNOWN NODE title_reference] 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.
New in version 0.9.
werkzeug.wsgi.get_script_name(environ, charset='utf-8', errors='replace')
Returns the [UNKNOWN NODE title_reference] from the WSGI environment and properly decodes it. This also takes care about the WSGI decoding dance on Python 3 environments. if the [UNKNOWN NODE title_reference] is set to [UNKNOWN NODE title_reference] a bytestring is returned.
New in version 0.9.
- environ – the WSGI environment object to get the path from.
- charset – the charset for the path, or [UNKNOWN NODE title_reference] if no decoding should be performed.
- errors – the decoding error handling.
werkzeug.wsgi.get_path_info(environ, charset='utf-8', errors='replace')
Returns the [UNKNOWN NODE title_reference] from the WSGI environment and properly decodes it. This also takes care about the WSGI decoding dance on Python 3 environments. if the [UNKNOWN NODE title_reference] is set to [UNKNOWN NODE title_reference] a bytestring is returned.
New in version 0.9.
- environ – the WSGI environment object to get the path from.
- charset – the charset for the path info, or [UNKNOWN NODE title_reference] if no decoding should be performed.
- errors – the decoding error handling.
werkzeug.wsgi.pop_path_info(environ, charset='utf-8', errors='replace')
Removes and returns the next segment of [UNKNOWN NODE title_reference], pushing it onto [UNKNOWN NODE title_reference]. Returns [UNKNOWN NODE title_reference] if there is nothing left on [UNKNOWN NODE title_reference].
If the [UNKNOWN NODE title_reference] is set to [UNKNOWN NODE title_reference] a bytestring is returned.
If there are empty segments ('/foo//bar
) these are ignored but
properly pushed to the [UNKNOWN NODE title_reference]:
New in version 0.5.
Changed in version 0.9: The path is now decoded and a charset and encoding parameter can be provided.
werkzeug.wsgi.peek_path_info(environ, charset='utf-8', errors='replace')
Returns the next segment on the [UNKNOWN NODE title_reference] or [UNKNOWN NODE title_reference] if there
is none. Works like pop_path_info()
without modifying the
environment:
If the [UNKNOWN NODE title_reference] is set to [UNKNOWN NODE title_reference] a bytestring is returned.
New in version 0.5.
Changed in version 0.9: The path is now decoded and a charset and encoding parameter can be provided.
werkzeug.wsgi.extract_path_info(environ_or_baseurl, path_or_url, charset='utf-8', errors='replace', collapse_http_schemes=True)
Extracts the path info from the given URL (or WSGI environment) and path. The path info returned is a unicode string, not a bytestring suitable for a WSGI environment. The URLs might also be IRIs.
If the path info could not be determined, [UNKNOWN NODE title_reference] is returned.
Some examples:
[UNKNOWN NODE doctest_block]Instead of providing a base URL you can also pass a WSGI environment.
New in version 0.6.
- environ_or_baseurl – a WSGI environment dict, a base URL or base IRI. This is the root of the application.
- path_or_url – an absolute path from the server root, a relative path (in which case it’s the path info) or a full URL. Also accepts IRIs and unicode parameters.
- charset – the charset for byte data in URLs
- errors – the error handling on decode
- collapse_http_schemes – if set to [UNKNOWN NODE title_reference] the algorithm does not assume that http and https on the same server point to the same resource.
werkzeug.wsgi.host_is_trusted(hostname, trusted_list)
Checks if a host is trusted against a list. This also takes care of port normalization.
New in version 0.9.
- hostname – the hostname to check
- trusted_list – a list of hostnames to check against. If a hostname starts with a dot it will match against all subdomains as well.
Convenience Helpers
werkzeug.wsgi.responder(f)
Marks a function as responder. Decorate a function with it and it will automatically call the return value as WSGI application.
Example:
@responder
def application(environ, start_response):
return Response('Hello World!')
werkzeug.testapp.test_app(environ, start_response)
Simple test application that dumps the environment. You can use it to check if Werkzeug is working properly:
>>> from werkzeug.serving import run_simple
>>> from werkzeug.testapp import test_app
>>> run_simple('localhost', 3000, test_app)
* Running on http://localhost:3000/
The application displays important information from the WSGI environment, the Python interpreter and the installed libraries.
Bytes, Strings, and Encodings
The WSGI environment on Python 3 works slightly different than it does on Python 2. Werkzeug hides the differences from you if you use the higher level APIs.
The WSGI specification (PEP 3333) decided to always use the native
str
type. On Python 2 this means the raw bytes are passed through
and can be decoded directly. On Python 3, however, the raw bytes are
always decoded using the ISO-8859-1 charset to produce a Unicode string.
Python 3 Unicode strings in the WSGI environment are restricted to ISO-8859-1 code points. If a string read from the environment might contain characters outside that charset, it must first be decoded to bytes as ISO-8859-1, then encoded to a Unicode string using the proper charset (typically UTF-8). The reverse is done when writing to the environ. This is known as the “WSGI encoding dance”.
Werkzeug provides functions to deal with this automatically so that you
don’t need to be aware of the inner workings. Use the functions on this
page as well as EnvironHeaders()
to read
data out of the WSGI environment.
Applications should avoid manually creating or modifying a WSGI environment unless they take care of the proper encoding or decoding step. All high level interfaces in Werkzeug will apply the encoding and decoding as necessary.