Werkzeug
Utilities
Navigation
Contents
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.
MultiDict
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 the 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.
You can construct a MultiDict from a list of (key, value) tuples, a dict or another MultiDict.
Basic Usage:
>>> from werkzeug.utils import MultiDict >>> 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.
The following additional functions exist that are used to get or set the other values for a key:
- getlist
- 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.
- setlist
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.
>>> multidict.setlist('foo', ['1', '2']) >>> multidict['foo'] '1' >>> multidict.getlist('foo') ['1', '2']
- setlistdefault
- Like setdefault but sets multiple values.
- lists
- Like items but the values will be lists with all the values for a key.
- listvalues
- Like values but it will return lists for all values instead of only the first value.
- iterlists
- Like lists but returns an iterator.
- iterlistvalues
- Like itervalues but it will yield lists for all values instead of only the first value.
- poplist
- Like pop for normal dicts; pops all the values for a key and removes the key from the dict.
- popitemlist
- Like popitem for normal dicts; pops all the values for a key, removes the key from the dict and then returns a tuple in the form (key, values).
Also notable: update adds values and does not replace existing.
CombinedMultiDict
A read only MultiDict decorator that you can pass multiple MultiDict instances as sequence and it will combine the return values of all wrapped dicts:
>>> from werkzeug.utils 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 want to change data which isn't possible.
Headers
Another useful class is Headers. It behaves in a similar to a MultiDict but it stores the values in a different way. In fact it's not a dict at all, it's more a list because the values are stored both sorted and unhashed.
This data structure is useful if you want a nicer way to handle WSGI headers which are stored as tuples in a list.
Changes to MultiDict:
iterlistvalues and listvalues are missing because itervalues and values work completely different.
- add
- Add a new value to a key foo.add('Content-Type', 'text/plain')
- __iter__
- yields (key, value) tuples.
- set / __setitem__
- remove all old keys and add a new value.
- to_list
- Convert the headers into a list and converts the unicode headers to the specified charset. The charset parameter is obligatory. (foo.to_list('utf-8'))
- getlist
- Return a list of allvalues for a given key
- setlist
- Add a list of values to a given key. Removes all old values for this key first.
- addlist
- Add a list of values to the headers for this key.
- itervalues and similar methods...
- ...yield all values for a key, not only the first one! iterkeys can of corse yield multiple keys with the same name analog to that.
FileStorage
The FileStorage object is a thin wrapper over incoming files. It has the following attributes and methods:
- name
- The name of the form field which represents the data.
- filename
- The incoming filename
- content_type
- The mimetype of the file. For example 'text/html'.
- content_length / len()
- The expected length of the file.
- read([bytes])
- Read bytes or all of the incoming file. Note that the default wrappers store the incoming data on the filesystem rather than the RAM. Thus you should keep in mind that reading without an maxmimum length can easily break your application if the user submitted data is too big.
- readline() / readlines() / __iter__
- Behave like the methods of any other file object.
- stream
- Gives you access to the underlaying stream. Note that the exact methods of this stream and it's type is not strictly specified. In most situations it will be a TemporaryFile object.
SharedDataMiddleware
A WSGI middleware that provides static content for development environments or simple server setups. Usage is quite simple:
import os from werkzeug.utils import SharedDataMiddleware app = SharedDataMiddleware(app, { '/shared': os.path.join(os.path.dirname(__file__), 'shared') })
The contents of the folder ./shared will now be available on http://example.com/shared/. This is pretty useful if you don't want to start a standalone media server or something like that.
Helper Functions
- url_decode(s, charset='utf-8')
- parse a querystring and return it as MultiDict.
- url_encode(s, charset='utf-8')
- URL encode a dict/MultiDict.
- url_quote(s, charset='utf-8')
- URL encode a single string with a given encoding.
- url_unquote(s, charset='utf-8')
- URL decode a single string with a given decoding.
- escape(s, quote=False)
- SGML/XML escape an unicode object or string.
- get_current_url(environ)
- Return the absolute, canonical URL for the current request.
- lazy_property(func)
A decorator that converts a function into a lazy property. The function wrapped is called the first time to retrieve the result and than that calculated result is used the next time you access the value.
class Foo(object): @lazy_property def foo(self): # calculate something important here return 42