# Werkzeug

# Data Structures

Werkzeug provides some subclasses of common Python objects to extend them with additional features. Some of them are used to make them immutable, others are used to change some semantics to better work with HTTP.

You can import all these objects directly from `werkzeug`.

## General Purpose

class `werkzeug.``TypeConversionDict`

  Works like a regular dict but the `get` method can perform type conversions. `MultiDict` and `CombinedMultiDict` are subclasses of this class and provide the same feature.

  New in version 0.5.

  `get`(key, default=None, type=None)

    Return the default value if the requested data doesn’t exist. If type is provided and is a callable it should convert the value, return it or raise a `ValueError` if that is not possible. In this case the function will return the default as if the value was not found:

        >>> d = TypeConversionDict(foo='42', bar='blub')
        >>> d.get('foo', type=int)
        42
        >>> d.get('bar', -1, type=int)
        -1

    Parameters: | key – The key to be looked up. default – The default value to be returned if the key can’t be looked up. If not further specified None is returned. type – A callable that is used to cast the value in the `MultiDict`. If a `ValueError` is raised by this callable the default value is returned.

class `werkzeug.``ImmutableTypeConversionDict`

  Works like a `TypeConversionDict` but does not support modifications.

  New in version 0.5.

  `copy`()
    Return a shallow mutable copy of this object. Keep in mind that the standard library’s `copy` funciton is a no-op for this class like for any other python immutable type (eg: `tuple`).

class `werkzeug.``MultiDict`(mapping=None)

  A `MultiDict` is a dictionary subclass customized to deal with multiple values for the same key which is for example used by the parsing functions in the wrappers. This is necessary because some HTML form elements pass multiple values for the same key.

  `MultiDict` implements all standard dictionary methods. Internally, it saves all values for a key as a list, but the standard dict access methods will only return the first value for a key. If you want to gain access to the other values, too, you have to use the list methods as explained below.

  Basic Usage:

      >>> d = MultiDict([('a', 'b'), ('a', 'c')])
      >>> d
      MultiDict([('a', 'b'), ('a', 'c')])
      >>> d['a']
      'b'
      >>> d.getlist('a')
      ['b', 'c']
      >>> 'a' in d
      True

  It behaves like a normal dict thus all dict functions will only return the first value when multiple values for one key are found.

  From Werkzeug 0.3 onwards, the KeyError raised by this class is also a subclass of the `BadRequest` HTTP exception and will render a page for a `400 BAD REQUEST` if catched in a catch-all for HTTP exceptions.

  A `MultiDict` can be constructed from an iterable of `(key, value)` tuples, a dict, a `MultiDict` or from Werkzeug 0.2 onwards some keyword parameters.

  Parameter: | mapping – the initial value for the `MultiDict`. Either a regular dict, an iterable of `(key, value)` tuples or None.

  `clear`()
    D.clear() -> None. Remove all items from D.
  `copy`()
    Return a shallow copy of this object.
  static `fromkeys`()
    dict.fromkeys(S[,v]) -> New dict with keys from S and values equal to v. v defaults to None.
  `get`(key, default=None, type=None)

    Return the default value if the requested data doesn’t exist. If type is provided and is a callable it should convert the value, return it or raise a `ValueError` if that is not possible. In this case the function will return the default as if the value was not found:

        >>> d = TypeConversionDict(foo='42', bar='blub')
        >>> d.get('foo', type=int)
        42
        >>> d.get('bar', -1, type=int)
        -1

    Parameters: | key – The key to be looked up. default – The default value to be returned if the key can’t be looked up. If not further specified None is returned. type – A callable that is used to cast the value in the `MultiDict`. If a `ValueError` is raised by this callable the default value is returned.

  `getlist`(key, type=None)

    Return the list of items for a given key. If that key is not in the MultiDict, the return value will be an empty list. Just as get getlist accepts a type parameter. All items will be converted with the callable defined there.

    Parameters: | key – The key to be looked up. type – A callable that is used to cast the value in the `MultiDict`. If a `ValueError` is raised by this callable the value will be removed from the list.
    Returns: | a `list` of all the values for the key.

  `has_key`()
    D.has_key(k) -> True if D has a key k, else False
  `items`(multi=False)

    Return a list of `(key, value)` pairs.

    Parameter: | multi – If set to True the list returned will have a pair for each value of each key. Ohterwise it will only contain pairs for the first value of each key.
    Returns: | a `list`

  `iteritems`(multi=False)
    Like `items` but returns an iterator.
  `iterkeys`()
    D.iterkeys() -> an iterator over the keys of D
  `iterlists`()

    Return a list of all values associated with a key.

    Returns: | a class:list

  `iterlistvalues`()
    like `listvalues` but returns an iterator.
  `itervalues`()
    Like `values` but returns an iterator.
  `keys`()
    D.keys() -> list of D’s keys
  `lists`()

    Return a list of `(key, value)` pairs, where values is the list of all values associated with the key.

    Returns: | a `list`

  `listvalues`()

    Return a list of all values associated with a key. Zipping `keys` and this is the same as calling `lists`:

        >>> d = MultiDict({"foo": [1, 2, 3]})
        >>> zip(d.keys(), d.listvalues()) == d.lists()
        True

    Returns: | a `list`

  `pop`(key, default=no value)

    Pop the first item for a list on the dict. Afterwards the key is removed from the dict, so additional values are discarded:

        >>> d = MultiDict({"foo": [1, 2, 3]})
        >>> d.pop("foo")
        1
        >>> "foo" in d
        False

    Parameters: | key – the key to pop. default – if provided the value to return if the key was not in the dictionary.

  `popitem`()
    Pop an item from the dict.
  `popitemlist`()
    Pop a `(key, list)` tuple from the dict.
  `poplist`(key)

    Pop the list for a key from the dict. If the key is not in the dict an empty list is returned.

    Changed in version 0.5: If the key does no longer exist a list is returned instead of raising an error.

  `setdefault`(key, default=None)

    Returns the value for the key if it is in the dict, otherwise it returns default and sets that value for key.

    Parameters: | key – The key to be looked up. default – The default value to be returned if the key is not in the dict. If not further specified it’s None.

  `setlist`(key, new_list)

    Remove the old values for a key and add new ones. Note that the list you pass the values in will be shallow-copied before it is inserted in the dictionary.

        >>> d = MultiDict()
        >>> d.setlist('foo', ['1', '2'])
        >>> d['foo']
        '1'
        >>> d.getlist('foo')
        ['1', '2']

    Parameters: | key – The key for which the values are set. new_list – An iterable with the new values for the key. Old values are removed first.

  `setlistdefault`(key, default_list=None)

    Like setdefault but sets multiple values. The list returned is not a copy, but the list that is actually used internally. This means that you can put new values into the dict by appending items to the list:

        >>> d = MultiDict({"foo": 1})
        >>> d.setlistdefault("foo").extend([2, 3])
        >>> d.getlist("foo")
        [1, 2, 3]

    Parameters: | key – The key to be looked up. default – An iterable of default values. It is either copied (in case it was a list) or converted into a list before returned.
    Returns: | a `list`

  `to_dict`(flat=True)

    Return the contents as regular dict. If flat is True the returned dict will only have the first item present, if flat is False all values will be returned as lists.

    Parameter: | flat – If set to False the dict returned will have lists with all the values in it. Otherwise it will only contain the first value for each key.
    Returns: | a `dict`

  `update`(other_dict)
    update() extends rather than replaces existing key lists.
  `values`()

    Returns a list of the first value on every key’s value list.

    Returns: | a `list`.

class `werkzeug.``ImmutableMultiDict`(mapping=None)

  An immutable `MultiDict`.

  New in version 0.5.

  `copy`()
    Return a shallow mutable copy of this object. Keep in mind that the standard library’s `copy` funciton is a no-op for this class like for any other python immutable type (eg: `tuple`).

class `werkzeug.``CombinedMultiDict`(dicts=None)

  A read only `MultiDict` that you can pass multiple `MultiDict` instances as sequence and it will combine the return values of all wrapped dicts:

      >>> from werkzeug import MultiDict, CombinedMultiDict
      >>> post = MultiDict([('foo', 'bar')])
      >>> get = MultiDict([('blub', 'blah')])
      >>> combined = CombinedMultiDict([get, post])
      >>> combined['foo']
      'bar'
      >>> combined['blub']
      'blah'

  This works for all read operations and will raise a TypeError for methods that usually change data which isn’t possible.

  From Werkzeug 0.3 onwards, the KeyError raised by this class is also a subclass of the `BadRequest` HTTP exception and will render a page for a `400 BAD REQUEST` if catched in a catch-all for HTTP exceptions.

class `werkzeug.``ImmutableDict`

  An immutable `dict`.

  New in version 0.5.

  `copy`()
    Return a shallow mutable copy of this object. Keep in mind that the standard library’s `copy` funciton is a no-op for this class like for any other python immutable type (eg: `tuple`).

class `werkzeug.``ImmutableList`

  An immutable `list`.

  New in version 0.5.

  Private: |

class `werkzeug.``FileMultiDict`(mapping=None)

  A special `MultiDict` that has convenience methods to add files to it. This is used for `EnvironBuilder` and generally useful for unittesting.

  New in version 0.5.

  `add_file`(name, file, filename=None, content_type=None)

    Adds a new file to the dict. file can be a file name or a `file`-like or a `FileStorage` object.

    Parameters: | name – the name of the field. file – a filename or `file`-like object filename – an optional filename content_type – an optional content type

## HTTP Related

class `werkzeug.``Headers`([defaults])

  An object that stores some headers. It has a dict-like interface but is ordered and can store the same keys multiple times.

  This data structure is useful if you want a nicer way to handle WSGI headers which are stored as tuples in a list.

  From Werkzeug 0.3 onwards, the `KeyError` raised by this class is also a subclass of the `BadRequest` HTTP exception and will render a page for a `400 BAD REQUEST` if catched in a catch-all for HTTP exceptions.

  Headers is mostly compatible with the Python `wsgiref.headers.Headers` class, with the exception of __getitem__. `wsgiref` will return None for `headers['missing']`, whereas `Headers` will raise a `KeyError`.

  To create a new `Headers` object pass it a list or dict of headers which are used as default values. This does not reuse the list passed to the constructor for internal usage. To create a `Headers` object that uses as internal storage the list or list-like object you can use the `linked` class method.

  Parameter: | defaults – The list of default values for the `Headers`.

  `add`(_key, _value, **kw)

    Add a new header tuple to the list.

    Keyword arguments can specify additional parameters for the header value, with underscores converted to dashes:

        >>> d = Headers()
        >>> d.add('Content-Type', 'text/plain')
        >>> d.add('Content-Disposition', 'attachment', filename='foo.png')

    The keyword argument dumping uses `dump_options_header` behind the scenes.

    New in version 0.4.1: keyword arguments were added for `wsgiref` compatibility.

  `add_header`(_key, _value, **_kw)

    Add a new header tuple to the list.

    An alias for `add` for compatibility with the `wsgiref` `add_header` method.

  `clear`()
    Clears all headers.
  `extend`(iterable)
    Extend the headers with a dict or an iterable yielding keys and values.
  `get`(key, default=None, type=None)

    Return the default value if the requested data doesn’t exist. If type is provided and is a callable it should convert the value, return it or raise a `ValueError` if that is not possible. In this case the function will return the default as if the value was not found:

        >>> d = Headers([('Content-Length', '42')])
        >>> d.get('Content-Length', type=int)
        42

    If a headers object is bound you must not add unicode strings because no encoding takes place.

    Parameters: | key – The key to be looked up. default – The default value to be returned if the key can’t be looked up. If not further specified None is returned. type – A callable that is used to cast the value in the `Headers`. If a `ValueError` is raised by this callable the default value is returned.

  `get_all`(name)

    Return a list of all the values for the named field.

    This method is compatible with the `wsgiref` `get_all` method.

  `getlist`(key, type=None)

    Return the list of items for a given key. If that key is not in the `Headers`, the return value will be an empty list. Just as `get` `getlist` accepts a type parameter. All items will be converted with the callable defined there.

    Parameters: | key – The key to be looked up. type – A callable that is used to cast the value in the `Headers`. If a `ValueError` is raised by this callable the value will be removed from the list.
    Returns: | a `list` of all the values for the key.

  `has_key`(key)
    Check if a key is present.
  classmethod `linked`(headerlist)

    Create a new `Headers` object that uses the list of headers passed as internal storage:

        >>> headerlist = [('Content-Length', '40')]
        >>> headers = Headers.linked(headerlist)
        >>> headers.add('Content-Type', 'text/html')
        >>> headerlist
        [('Content-Length', '40'), ('Content-Type', 'text/html')]

    Parameter: | headerlist – The list of headers the class is linked to.
    Returns: | new linked `Headers` object.

  `pop`(key=None, default=no value)

    Removes and returns a key or index.

    Parameter: | key – The key to be popped. If this is an integer the item at that position is removed, if it’s a string the value for that key is. If the key is omitted or None the last item is removed.
    Returns: | an item.

  `popitem`()
    Removes a key or index and returns a (key, value) item.
  `remove`(key)

    Remove a key.

    Parameter: | key – The key to be removed.

  `set`(key, value)

    Remove all header tuples for key and add a new one. The newly added key either appears at the end of the list if there was no entry or replaces the first one.

    Parameters: | key – The key to be inserted. value – The value to be inserted.

  `setdefault`(key, value)

    Returns the value for the key if it is in the dict, otherwise it returns default and sets that value for key.

    Parameters: | key – The key to be looked up. default – The default value to be returned if the key is not in the dict. If not further specified it’s None.

  `to_list`(charset='utf-8')

    Convert the headers into a list and converts the unicode header items to the specified charset.

    Returns: | list

class `werkzeug.``EnvironHeaders`(environ)

  Read only version of the headers from a WSGI environment. This provides the same interface as Headers and is constructed from a WSGI environment.

  From Werkzeug 0.3 onwards, the KeyError raised by this class is also a subclass of the `BadRequest` HTTP exception and will render a page for a `400 BAD REQUEST` if catched in a catch-all for HTTP exceptions.

class `werkzeug.``HeaderSet`(headers=None, on_update=None)

  Similar to the `ETags` class this implements a set-like structure. Unlike `ETags` this is case insensitive and used for vary, allow, and content-language headers.

  If not constructed using the `parse_set_header` function the instantiation works like this:

      >>> hs = HeaderSet(['foo', 'bar', 'baz'])
      >>> hs
      HeaderSet(['foo', 'bar', 'baz'])

  `add`(header)
    Add a new header to the set.
  `as_set`(preserve_casing=False)

    Return the set as real python set type. When calling this, all the items are converted to lowercase and the ordering is lost.

    Parameter: | preserve_casing – if set to True the items in the set returned will have the original case like in the `HeaderSet`, otherwise they will be lowercase.

  `clear`()
    Clear the set.
  `discard`(header)

    Like `remove` but ignores errors.

    Parameter: | header – the header to be discarded.

  `find`(header)

    Return the index of the header in the set or return -1 if not found.

    Parameter: | header – the header to be looked up.

  `index`(header)

    Return the index of the header in the set or raise an `IndexError`.

    Parameter: | header – the header to be looked up.

  `remove`(header)

    Remove a layer from the set. This raises an `KeyError` if the header is not in the set.

    Changed in version 0.5: In older versions a `IndexError` was raised instead of a `KeyError` if the object was missing.

    Parameter: | header – the header to be removed.

  `to_header`()
    Convert the header set into an HTTP header string.
  `update`(iterable)

    Add all the headers from the iterable to the set.

    Parameter: | iterable – updates the set with the items from the iterable.

class `werkzeug.``Accept`(values=())

  An `Accept` object is just a list subclass for lists of `(value, quality)` tuples. It is automatically sorted by quality.

  All `Accept` objects work similar to a list but provide extra functionality for working with the data. Containment checks are normalized to the rules of that header:

      >>> a = CharsetAccept([('ISO-8859-1', 1), ('utf-8', 0.7)])
      >>> a.best
      'ISO-8859-1'
      >>> 'iso-8859-1' in a
      True
      >>> 'UTF8' in a
      True
      >>> 'utf7' in a
      False

  To get the quality for an item you can use normal item lookup:

      >>> print a['utf-8']
      0.7
      >>> a['utf7']
      0

  Changed in version 0.5: `Accept` objects are forzed immutable now.

  `best`
    The best match as value.
  `find`(key)

    Get the position of an entry or return -1.

    Parameter: | key – The key to be looked up.

  `index`(key)

    Get the position of an entry or raise `ValueError`.

    Parameter: | key – The key to be looked up.

    Changed in version 0.5: This used to raise `IndexError`, which was inconsistent with the list API.

  `itervalues`()
    Iterate over all values.
  `to_header`()
    Convert the header set into an HTTP header string.
  `values`()
    Return a list of the values, not the qualities.

class `werkzeug.``MIMEAccept`(values=())

  Like `Accept` but with special methods and behavior for mimetypes.

  `accept_html`
    True if this object accepts HTML.
  `accept_xhtml`
    True if this object accepts XHTML.

class `werkzeug.``CharsetAccept`(values=())
  Like `Accept` but with normalization for charsets.

class `werkzeug.``LanguageAccept`(values=())
  Like `Accept` but with normalization for languages.

class `werkzeug.``RequestCacheControl`(values=(), on_update=None)

  A cache control for requests. This is immutable and gives access to all the request-relevant cache control headers.

  New in version 0.5: In previous versions a CacheControl class existed that was used both for request and response.

  `no_cache`
    accessor for ‘no-cache’
  `no_store`
    accessor for ‘no-store’
  `max_age`
    accessor for ‘max-age’
  `no_transform`
    accessor for ‘no-transform’
  `max_stale`
    accessor for ‘max-stale’
  `min_fresh`
    accessor for ‘min-fresh’
  `no_transform`
    accessor for ‘no-transform’
  `only_if_cached`
    accessor for ‘only-if-cached’

class `werkzeug.``ResponseCacheControl`(values=(), on_update=None)

  A cache control for responses. Unlike `RequestCacheControl` this is mutable and gives access to response-relevant cache control headers.

  New in version 0.5: In previous versions a CacheControl class existed that was used both for request and response.

  `no_cache`
    accessor for ‘no-cache’
  `no_store`
    accessor for ‘no-store’
  `max_age`
    accessor for ‘max-age’
  `no_transform`
    accessor for ‘no-transform’
  `must_revalidate`
    accessor for ‘must-revalidate’
  `private`
    accessor for ‘private’
  `proxy_revalidate`
    accessor for ‘proxy-revalidate’
  `public`
    accessor for ‘public’
  `s_maxage`
    accessor for ‘s-maxage’

class `werkzeug.``ETags`(strong_etags=None, weak_etags=None, star_tag=False)

  A set that can be used to check if one etag is present in a collection of etags.

  `as_set`(include_weak=False)
    Convert the ETags object into a python set. Per default all the weak etags are not part of this set.
  `contains`(etag)
    Check if an etag is part of the set ignoring weak tags.
  `contains_raw`(etag)
    When passed a quoted tag it will check if this tag is part of the set. If the tag is weak it is checked against weak and strong tags, otherwise weak only.
  `contains_weak`(etag)
    Check if an etag is part of the set including weak and strong tags.
  `is_weak`(etag)
    Check if an etag is weak.
  `to_header`()
    Convert the etags set into a HTTP header string.

class `werkzeug.``Authorization`(auth_type, data=None)

  Represents an Authorization header sent by the client. You should not create this kind of object yourself but use it when it’s returned by the parse_authorization_header function.

  This object is a dict subclass and can be altered by setting dict items but it should be considered immutable as it’s returned by the client and not meant for modifications.

  Changed in version 0.5: This object became immutable.

  `cnonce`
    If the server sent a qop-header in the `WWW-Authenticate` header, the client has to provide this value for HTTP digest auth. See the RFC for more details.
  `nc`
    The nonce count value transmitted by clients if a qop-header is also transmitted. HTTP digest auth only.
  `nonce`
    The nonce the server sent for digest auth, sent back by the client. A nonce should be unique for every 401 response for HTTP digest auth.
  `opaque`
    The opaque header from the server returned unchanged by the client. It is recommended that this string be base64 or hexadecimal data. Digest auth only.
  `password`
    When the authentication type is basic this is the password transmitted by the client, else None.
  `qop`
    Indicates what “quality of protection” the client has applied to the message for HTTP digest auth.
  `realm`
    This is the server realm sent back for HTTP digest auth.
  `response`
    A string of 32 hex digits computed as defined in RFC 2617, which proves that the user knows a password. Digest auth only.
  `uri`
    The URI from Request-URI of the Request-Line; duplicated because proxies are allowed to change the Request-Line in transit. HTTP digest auth only.
  `username`
    The username transmitted. This is set for both basic and digest auth all the time.

class `werkzeug.``WWWAuthenticate`(auth_type=None, values=None, on_update=None)

  Provides simple access to WWW-Authenticate headers.

  `algorithm`
    A string indicating a pair of algorithms used to produce the digest and a checksum. If this is not present it is assumed to be “MD5”. If the algorithm is not understood, the challenge should be ignored (and a different one used, if there is more than one).
  static `auth_property`(name, doc=None)

    A static helper function for subclasses to add extra authentication system properites onto a class:

        class FooAuthenticate(WWWAuthenticate):
            special_realm = auth_property('special_realm')

    For more information have a look at the sourcecode to see how the regular properties (`realm` etc. are implemented).

  `domain`
    A list of URIs that define the protection space. If a URI is an absolute path, it is relative to the canonical root URL of the server being accessed.
  `nonce`
    A server-specified data string which should be uniquely generated each time a 401 response is made. It is recommended that this string be base64 or hexadecimal data.
  `opaque`
    A string of data, specified by the server, which should be returned by the client unchanged in the Authorization header of subsequent requests with URIs in the same protection space. It is recommended that this string be base64 or hexadecimal data.
  `qop`
    A set of quality-of-privacy modifies such as auth and auth-int.
  `realm`
    A string to be displayed to users so they know which username and password to use. This string should contain at least the name of the host performing the authentication and might additionally indicate the collection of users who might have access.
  `set_basic`(realm='authentication required')
    Clear the auth info and enable basic auth.
  `set_digest`(realm, nonce, qop=('auth', ), opaque=None, algorithm=None, stale=False)
    Clear the auth info and enable digest auth.
  `stale`
    A flag, indicating that the previous request from the client was rejected because the nonce value was stale.
  `to_header`()
    Convert the stored values into a WWW-Authenticate header.
  `type`
    The type of the auth mechanism. HTTP currently specifies Basic and Digest.

## Others

class `werkzeug.``FileStorage`(stream=None, filename=None, name=None, content_type='application/octet-stream', content_length=-1)

  The `FileStorage` class is a thin wrapper over incoming files. It is used by the request object to represent uploaded files. All the attributes of the wrapper stream are proxied by the file storage so it’s possible to do `storage.read()` instead of the long form `storage.stream.read()`.

  `stream`
    The input stream for the uploaded file. This usually points to an open temporary file.
  `filename`
    The filename of the file on the client.
  `name`
    The name of the form field.
  `content_type`
    The content type (mimetype) of the file.
  `content_length`
    The length of the file in bytes.
  `close`()
    Close the underlaying file if possible.
  `save`(dst, buffer_size=16384)

    Save the file to a destination path or file object. If the destination is a file object you have to close it yourself after the call. The buffer size is the number of bytes held in memory during the copy process. It defaults to 16KB.

    For secure file saving also have a look at `secure_filename`.

    Parameters: | dst – a filename or open file object the uploaded file is saved to. buffer_size – the size of the buffer. This works the same as the length parameter of `shutil.copyfileobj`.