WSGI Helpers — Werkzeug documentation

WSGI Helpers

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.

Environ Helpers

These functions operate on the WSGI environment. They extract useful information or perform common manipulations:

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.

Raw Request URI and Path Encoding

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.