WSGI Helpers
============

.. module:: werkzeug.wsgi

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
:doc:`/wrappers`.


Iterator / Stream Helpers
-------------------------

These classes and functions simplify working with the WSGI application
iterator and the input stream.

.. autoclass:: ClosingIterator

.. autoclass:: FileWrapper

.. autoclass:: LimitedStream
    :members:

.. autofunction:: wrap_file


Environ Helpers
---------------

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

.. autofunction:: get_host

.. autofunction:: get_content_length

.. autofunction:: get_input_stream

.. autofunction:: get_current_url

.. autofunction:: host_is_trusted


Convenience Helpers
-------------------

.. autofunction:: responder

.. autofunction:: werkzeug.testapp.test_app


Bytes, Strings, and Encodings
-----------------------------

The values in HTTP requests come in as bytes representing (or encoded
to) ASCII. The WSGI specification (:pep:`3333`) decided to always use
the ``str`` type to represent values. To accomplish this, the raw bytes
are decoded using the ISO-8859-1 charset to produce a string.

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 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 :func:`~werkzeug.datastructures.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.