=========
Utilities
=========

Werkzeug comes with a bunch of utilties that can be useful for WSGI
applications.  Most of the classes provided by this module are used by the
wrappers, you can however use them without the wrappers, too.

All the utilities can be directly imported from the `werkzeug` module.


Data Structures
===============

.. class:: werkzeug.utils.MultiDict

    The following additional methods exist that are used to get or set the
    other values for a key or convert:

    .. def:: werkzeug.utils.MultiDict.get
    .. def:: werkzeug.utils.MultiDict.getlist
    .. def:: werkzeug.utils.MultiDict.setlist
    .. def:: werkzeug.utils.MultiDict.setlistdefault

    These functions work like the functions with the same name without
    list.  Unlike the regular dict functions those operate on all the
    values as lists, not only on the first one:

    `lists`, `listvalues`, `iterlists`, `iterlistvalues`, `poplist`,
    and `popitemlist`.

    Also notable: `update` adds values and does not replace existing ones.


.. class:: werkzeug.utils.CombinedMultiDict

.. class:: werkzeug.utils.Headers

    .. def:: werkzeug.utils.Headers.__init__
    .. def:: werkzeug.utils.Headers.linked
    .. def:: werkzeug.utils.Headers.get
    .. def:: werkzeug.utils.Headers.getlist
    .. def:: werkzeug.utils.Headers.add
    .. def:: werkzeug.utils.Headers.set
    .. def:: werkzeug.utils.Headers.extend
    .. def:: werkzeug.utils.Headers.clear
    .. def:: werkzeug.utils.Headers.to_list
    .. def:: werkzeug.utils.Headers.__contains__
    .. def:: werkzeug.utils.Headers.__iter__

    All the other dict functions such as `iterkeys` are available and
    work the same.


.. class:: werkzeug.utils.EnvironHeaders


Working with HTTP Headers
=========================

.. def:: werkzeug.http.parse_set_header
.. def:: werkzeug.http.parse_list_header
.. def:: werkzeug.http.parse_dict_header
.. def:: werkzeug.http.dump_header

.. class:: werkzeug.http.Accept

    `provided`
        `True` if the `Accept` object was created from a list, `False` if the
        initial value was `None`.  This is used by the request wrappers to
        keep the information if the header was present or not.

    `best`
        The best value (does not return a tuple!).

    .. def:: werkzeug.http.Accept.__getitem__
    .. def:: werkzeug.http.Accept.find
    .. def:: werkzeug.http.Accept.values
    .. def:: werkzeug.http.Accept.itervalues

.. def:: werkzeug.http.parse_accept_header

.. class:: werkzeug.http.CacheControl
.. def:: werkzeug.http.parse_cache_control_header

.. class:: werkzeug.http.HeaderSet

    .. def:: werkzeug.http.HeaderSet.add
    .. def:: werkzeug.http.HeaderSet.remove
    .. def:: werkzeug.http.HeaderSet.update
    .. def:: werkzeug.http.HeaderSet.discard
    .. def:: werkzeug.http.HeaderSet.find
    .. def:: werkzeug.http.HeaderSet.index
    .. def:: werkzeug.http.HeaderSet.clear
    .. def:: werkzeug.http.HeaderSet.as_set
    .. def:: werkzeug.http.HeaderSet.to_header

.. class:: werkzeug.useragents.UserAgent

.. def:: werkzeug.http.parse_date
.. def:: werkzeug.utils.cookie_date
.. def:: werkzeug.utils.http_date
.. def:: werkzeug.utils.parse_form_data

.. class:: werkzeug.http.ETags

    .. def:: werkzeug.http.ETags.is_weak
    .. def:: werkzeug.http.ETags.contains_weak
    .. def:: werkzeug.http.ETags.contains
    .. def:: werkzeug.http.ETags.contains_raw
    .. def:: werkzeug.http.ETags.as_set
    .. def:: werkzeug.http.ETags.to_header

.. def:: werkzeug.http.parse_etags
.. def:: werkzeug.http.quote_etag
.. def:: werkzeug.http.unquote_etag
.. def:: werkzeug.http.generate_etag
.. def:: werkzeug.http.is_resource_modified

.. class:: werkzeug.http.Authorization

    .. def:: werkzeug.http.WWWAuthenticate.to_header
    .. property:: werkzeug.http.Authorization.username
    .. property:: werkzeug.http.Authorization.password
    .. property:: werkzeug.http.Authorization.realm
    .. property:: werkzeug.http.Authorization.nonce
    .. property:: werkzeug.http.Authorization.uri
    .. property:: werkzeug.http.Authorization.nc
    .. property:: werkzeug.http.Authorization.cnonce
    .. property:: werkzeug.http.Authorization.response
    .. property:: werkzeug.http.Authorization.opaque
    .. property:: werkzeug.http.Authorization.qop

.. class:: werkzeug.http.WWWAuthenticate

    .. def:: werkzeug.http.WWWAuthenticate.set_basic
    .. def:: werkzeug.http.WWWAuthenticate.set_digest
    .. def:: werkzeug.http.WWWAuthenticate.to_header
    .. property:: werkzeug.http.WWWAuthenticate.type
    .. property:: werkzeug.http.WWWAuthenticate.realm
    .. property:: werkzeug.http.WWWAuthenticate.stale
    .. property:: werkzeug.http.WWWAuthenticate.domain
    .. property:: werkzeug.http.WWWAuthenticate.nonce
    .. property:: werkzeug.http.WWWAuthenticate.opaque
    .. property:: werkzeug.http.WWWAuthenticate.algorithm
    .. property:: werkzeug.http.WWWAuthenticate.qop

.. def:: werkzeug.http.parse_authorization_header
.. def:: werkzeug.http.parse_www_authenticate_header

`HTTP_STATUS_CODES`
    A dict of status code -> default status message pairs.  This is used
    by the wrappers and other places where a integer status code is expanded
    to a string throughout Werkzeug.


URL Helpers
===========

.. def:: werkzeug.utils.url_decode
.. def:: werkzeug.utils.url_encode
.. def:: werkzeug.utils.url_quote
.. def:: werkzeug.utils.url_quote_plus
.. def:: werkzeug.utils.url_unquote
.. def:: werkzeug.utils.url_unquote_plus
.. def:: werkzeug.utils.url_fix
.. class:: werkzeug.utils.Href


HTML Helpers
============

.. def:: werkzeug.utils.escape
.. def:: werkzeug.utils.unescape
.. class:: werkzeug.utils.HTMLBuilder


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

.. class:: werkzeug.utils.ClosingIterator
.. class:: werkzeug.utils.SharedDataMiddleware
.. class:: werkzeug.utils.DispatcherMiddleware
.. class:: werkzeug.utils.FileStorage

    `name`
        The name of the form field which represents the data.

    `filename`
        The incoming filename.

    `content_type`
        The mimetype of the file.  E.g. ``'text/html'``.

    `content_length / len()`
        The expected length of the file.

    `stream`
        Gives you access to the underlaying stream.  Note that the exact
        methods of this stream and its type is not strictly specified.  In
        most situations it will be a `TemporaryFile` object.

    .. def:: werkzeug.utils.FileStorage.__init__
    .. def:: werkzeug.utils.FileStorage.save

.. def:: werkzeug.utils.get_host
.. def:: werkzeug.utils.get_current_url
.. def:: werkzeug.utils.responder
.. def:: werkzeug.utils.create_environ
.. def:: werkzeug.utils.run_wsgi_app


Helper Functions
================

.. def:: werkzeug.utils.cached_property
.. def:: werkzeug.utils.environ_property
.. def:: werkzeug.utils.header_property
.. def:: werkzeug.utils.parse_cookie
.. def:: werkzeug.utils.dump_cookie
.. def:: werkzeug.utils.redirect
.. def:: werkzeug.utils.append_slash_redirect
.. def:: werkzeug.utils.import_string
.. def:: werkzeug.utils.find_modules
.. def:: werkzeug.utils.validate_arguments
.. def:: werkzeug.utils.bind_arguments
.. def:: werkzeug.testapp.test_app