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.
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 close
callback of the iterable returned by the application. Because it is useful to add another close action to a returned iterable and adding a custom iterable 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 buffer_size
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 direct_passthrough
mode.
Parameters: |
|
---|
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.
Parameters: |
|
---|
exhaust(chunk_size=65536)
Exhaust the stream. This consumes all the data left until the limit is reached.
Parameters: | chunk_size – the size for a chunk. It will read the chunk until the stream is exhausted and throw away the results. |
---|
is_exhausted
If the stream is exhausted this attribute is True
.
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 size
bytes or if size is not provided everything is read.
Parameters: | size – the number of bytes read. |
---|
readable()
Return whether object was opened for reading.
If False, read() will raise OSError.
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 size
argument if the underlying stream supports it for readline
.
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 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.
New in version 0.11.10: added support for the cap_at_buffer
parameter.
New in version 0.9: added support for iterators as input stream.
Changed in version 0.8: This function now ensures that the limit was reached.
Parameters: |
|
---|
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.11.10: added support for the cap_at_buffer
parameter.
New in version 0.9: added support for iterators as input stream.
New in version 0.8.
Parameters: |
|
---|
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 True
.
More information about file wrappers are available in PEP 333.
Parameters: |
|
---|
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 host for the given WSGI environment. This first checks the Host
header. If it’s not present, then SERVER_NAME
and SERVER_PORT
are used. The host will only contain the port if it is different than the standard port for the protocol.
Optionally, verify that the host is trusted using host_is_trusted()
and raise a SecurityError
if it is not.
Parameters: |
|
---|---|
Returns: |
Host, with port if necessary. |
Raises: |
SecurityError – If the host is not trusted. |
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.
Parameters: | environ – the WSGI environ to fetch the content length from. |
---|
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.
Parameters: |
|
---|
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:
>>> from werkzeug.test import create_environ >>> env = create_environ("/?param=foo", "http://localhost/script") >>> get_current_url(env) 'http://localhost/script/?param=foo' >>> get_current_url(env, root_only=True) 'http://localhost/script/' >>> get_current_url(env, host_only=True) 'http://localhost/' >>> get_current_url(env, strip_querystring=True) 'http://localhost/script/'
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:
>>> from werkzeug.urls import iri_to_uri >>> iri_to_uri(get_current_url(env)) 'http://localhost/script/?param=foo'
Parameters: |
|
---|
werkzeug.wsgi.get_query_string(environ)
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.
New in version 0.9.
Parameters: | environ – the WSGI environment object to get the query string from. |
---|
werkzeug.wsgi.get_script_name(environ, charset='utf-8', errors='replace')
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: |
|
---|
werkzeug.wsgi.get_path_info(environ, charset='utf-8', errors='replace')
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: |
|
---|
werkzeug.wsgi.pop_path_info(environ, charset='utf-8', errors='replace')
Removes and returns the next segment of PATH_INFO
, pushing it onto SCRIPT_NAME
. Returns None
if there is nothing left on PATH_INFO
.
If the charset
is set to None
a bytestring is returned.
If there are empty segments ('/foo//bar
) these are ignored but properly pushed to the SCRIPT_NAME
:
>>> env = {'SCRIPT_NAME': '/foo', 'PATH_INFO': '/a/b'} >>> pop_path_info(env) 'a' >>> env['SCRIPT_NAME'] '/foo/a' >>> pop_path_info(env) 'b' >>> env['SCRIPT_NAME'] '/foo/a/b'
Changed in version 0.9: The path is now decoded and a charset and encoding parameter can be provided.
New in version 0.5.
Parameters: | environ – the WSGI environment that is modified. |
---|
werkzeug.wsgi.peek_path_info(environ, charset='utf-8', errors='replace')
Returns the next segment on the PATH_INFO
or None
if there is none. Works like pop_path_info()
without modifying the environment:
>>> env = {'SCRIPT_NAME': '/foo', 'PATH_INFO': '/a/b'} >>> peek_path_info(env) 'a' >>> peek_path_info(env) 'a'
If the charset
is set to None
a bytestring is returned.
Changed in version 0.9: The path is now decoded and a charset and encoding parameter can be provided.
New in version 0.5.
Parameters: | environ – the WSGI environment that is checked. |
---|
werkzeug.wsgi.extract_path_info(environ_or_baseurl, path_or_url, charset='utf-8', errors='werkzeug.url_quote', 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, None
is returned.
Some examples:
>>> extract_path_info('http://example.com/app', '/app/hello') u'/hello' >>> extract_path_info('http://example.com/app', ... 'https://example.com/app/hello') u'/hello' >>> extract_path_info('http://example.com/app', ... 'https://example.com/app/hello', ... collapse_http_schemes=False) is None True
Instead of providing a base URL you can also pass a WSGI environment.
Parameters: |
|
---|
Changed in version 0.15: The errors
parameter defaults to leaving invalid bytes quoted instead of replacing them.
New in version 0.6.
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.
Parameters: |
|
---|
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.
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.
The PATH_INFO
in the environ is the path value after percent-decoding. For example, the raw path /hello%2fworld
would show up from the WSGI server to Werkzeug as /hello/world
. This loses the information that the slash was a raw character as opposed to a path separator.
The WSGI specification (PEP 3333) does not provide a way to get the original value, so it is impossible to route some types of data in the path. The most compatible way to work around this is to send problematic data in the query string instead of the path.
However, many WSGI servers add a non-standard environ key with the raw path. To match this behavior, Werkzeug’s test client and development server will add the raw value to both the REQUEST_URI
and RAW_URI
keys. If you want to route based on this value, you can use middleware to replace PATH_INFO
in the environ before it reaches the application. However, keep in mind that these keys are non-standard and not guaranteed to be present.
© 2007–2020 Pallets
Licensed under the BSD 3-clause License.
https://werkzeug.palletsprojects.com/en/1.0.x/wsgi/