Werkzeug

The Swiss Army Knife For Python Web Developers

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 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.

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.

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

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.

Example:

>>> d = MultiDict(foo='42', bar='blub')
>>> d.get('foo', type=int)
42
>>> d.get('bar', -1, type=int)
-1
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.

returns: list

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.

>>> multidict.setlist('foo', ['1', '2'])
>>> multidict['foo']
'1'
>>> multidict.getlist('foo')
['1', '2']
setlistdefault (key, default_list=())
Like setdefault but sets multiple values.

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 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 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.

class Headers

An object that stores some headers. It has a dict like interface but is ordered and can store 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.

__init__ (defaults=None, _list=None)
Create a new Headers object based on 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 provided it’s possible to use the linked 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')]

returns: new linked Headers object.

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.

Example:

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

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

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.

returns: list

add (key, value)
add a new header tuple to the list
set (key, value)
remove all header tuples for key and add a new one
extend (iterable)
Extend the headers with a dict or an iterable yielding keys and values.
clear ()
clears all headers
to_list (charset='utf-8')

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

returns: list

__contains__ (key)
Check if a key is present.
__iter__ ()
Yield (key, value) tuples.

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

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

Working with HTTP Headers

class Accept

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

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!).
__getitem__ (key)
Beside index lookup (getting item n) you can also pass it a string to get the quality for the item. If the item is not in the list, the returned quality is 0.
find (key)
Get the position of an entry or return -1
values ()
Return a list of the values, not the qualities.
itervalues ()
Iterate over all values.
parse_accept_header (value)

Parses an HTTP Accept-* header. This does not implement a complete valid algorithm but one that supports at least value and quality extraction.

Returns a new Accept object (basicly a list of (value, quality) tuples sorted by the quality with some additional accessor methods)

class CacheControl

Subclass of a dict that stores values for a Cache-Control header. It has accesors for all the cache-control directives specified in RFC 2616. The class does not differentiate between request and response directives.

Because the cache-control directives in the HTTP header use dashes the python descriptors use underscores for that.

To get a header of the CacheControl object again you can convert the object into a string or call the to_header() function. If you plan to subclass it and add your own items have a look at the sourcecode for that class.

The following attributes are exposed:

no_cache, no_store, max_age, max_stale, min_fresh, no_transform, only_if_cached, public, private, must_revalidate, proxy_revalidate, and s_maxage

parse_cache_control_header (value, on_update=None)
Parse a cache control header. The RFC differs between response and request cache control, this method does not. It’s your responsibility to not use the wrong control statements.
class HeaderSet

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 instanciation works like this:

>>> hs = HeaderSet(['foo', 'bar', 'baz'])
>>> hs
HeaderSet(['foo', 'bar', 'baz'])
add (header)
Add a new header to the set.
remove (header)
Remove a layer from the set. This raises an IndexError if the header is not in the set.
update (iterable)
Add all the headers from the iterable to the set.
discard (header)
Like remove but ignores errors.
find (header)
Return the index of the header in the set or return -1 if not found.
index (header)
Return the index of the headerin the set or raise an IndexError.
clear ()
Clear the set.
as_set (preserve_casing=False)

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

If preserve_casing is True the items in the set returned will have the original case like in the HeaderSet, otherwise they will be lowercase.

to_header ()
Convert the header set into an HTTP header string.
parse_set_header (value, on_update=None)
Parse a set like header and return a HeaderSet object. The return value is an object that treats the items case insensitive and keeps the order of the items.
class UserAgent

Represents a user agent. Pass it a WSGI environment or an user agent string and you can inspect some of the details from the user agent string via the attributes. The following attribute exist:

  • string, the raw user agent string
  • platform, the browser platform
  • browser, the name of the browser
  • version, the version of the browser
  • language, the language of the browser
parse_date (value)

Parse one of the following date formats into a datetime object:

Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123
Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format

If parsing fails the return value is None.

class ETags

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

is_weak (etag)
Check if an etag is weak.
contains_weak (etag)
Check if an etag is part of the set including weak and strong tags.
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.
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.
to_header ()
Convert the etags set into a HTTP header string.
parse_etags (value)
Parse and etag header. Returns an ETags object.
quote_etag (etag, weak=False)
Quote an etag.
unquote_etag (etag)
Unquote a single etag. Return a (etag, weak) tuple.
generate_etag (data)
Generate an etag for some data.
is_resource_modified (environ, etag=None, data=None, last_modified=None)
Convenience method for conditional requests.
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

url_decode (s, charset='utf-8', decode_keys=False, include_empty=True)

Parse a querystring and return it as MultiDict. Per default only values are decoded into unicode strings. If decode_keys is set to True the same will happen for keys.

Per default a missing value for a key will default to an empty key. If you don’t want that behavior you can set include_empty to False.

url_encode (obj, charset='utf-8', encode_keys=False)
URL encode a dict/MultiDict. If a value is None it will not appear in the result string. Per default only values are encoded into the target charset strings. If encode_keys is set to True unicode keys are supported too.
url_quote (s, charset='utf-8', safe='/:')
URL encode a single string with a given encoding.
url_quote_plus (s, charset='utf-8', safe='')
URL encode a single string with the given encoding and convert whitespace to “+”.
url_unquote (s, charset='utf-8')
URL decode a single string with a given decoding.
url_unquote_plus (s, charset='utf-8')
URL decode a single string with the given decoding and decode a “+” to whitespace.
url_fix (s, charset='utf-8')

Sometimes you get an URL by a user that just isn’t a real URL because it contains unsafe characters like ‘ ‘ and so on. This function can fix some of the problems in a similar way browsers handle data entered by the user:

>>> url_fix(u'http://de.wikipedia.org/wiki/Elf (Begriffsklärung)')
'http://de.wikipedia.org/wiki/Elf%20%28Begriffskl%C3%A4rung%29'
Parameters
charset: The target charset for the URL if the url was given as unicode string.
class Href

Implements a callable that constructs URLs with the given base. The function can be called with any number of positional and keyword arguments which than are used to assemble the URL. Works with URLs and posix paths.

Positional arguments are appended as individual segments to the path of the URL:

>>> href = Href('/foo')
>>> href('bar', 23)
'/foo/bar/23'
>>> href('foo', bar=23)
'/foo/foo?bar=23'

If any of the arguments (positional or keyword) evaluates to None it will be skipped. If no keyword arguments are given the last argument can be a dict or MultiDict (or any other dict subclass), otherwise the keyword arguments are used for the query parameters, cutting off the first trailing underscore of the parameter name:

>>> href(is_=42)
'/foo?is=42'

Accessing attributes on the href object creates a new href object with the attribute name as prefix:

>>> bar_href = href.bar
>>> bar_href("blub")
'/foo/bar/blub'

HTML Helpers

escape (s, quote=None)

Replace special characters “&”, “<” and “>” to HTML-safe sequences. If the optional flag quote is True, the quotation mark character (“) is also translated.

There is a special handling for None which escapes to an empty string.

unescape (s)
The reverse function of escape. This unescapes all the HTML entities, not only the XML entities inserted by escape.
class HTMLBuilder

Helper object for HTML generation.

Per default there are two instances of that class. The html one, and the xhtml one for those two dialects. The class uses keyword parameters and positional parameters to generate small snippets of HTML.

Keyword parameters are converted to XML/SGML attributes, positional arguments are used as children. Because Python accepts positional arguments before keyword arguments it’s a good idea to use a list with the star-syntax for some children:

>>> html.p(class_='foo', *[html.a('foo', href='foo.html'), ' ',
...                        html.a('bar', href='bar.html')])
'<p class="foo"><a href="foo.html">foo</a> <a href="bar.html">bar</a></p>'

This class works around some browser limitations and can not be used for arbitrary SGML/XML generation. For that purpose lxml and similar libraries exist.

Calling the builder escapes the string passed:

>>> html.p(html("<foo>"))
'<p>&lt;foo&gt;</p>'

WSGI Helpers

class ClosingIterator

The WSGI specification requires that all middlewares and gateways respect the close callback of an iterator. Because it is useful to add another close action to a returned iterator and adding a custom iterator is a boring task this class can be used for that:

return ClosingIterator(app(environ, start_response), [cleanup_session,
                                                      cleanup_locals])

If there is just one close function it can be bassed instead of the list.

A closing iterator is non needed if the application uses response objects and finishes the processing if the resonse is started:

try:
    return response(environ, start_response)
finally:
    cleanup_session()
    cleanup_locals()
class SharedDataMiddleware

A WSGI middleware that provides static content for development environments or simple server setups. Usage is quite simple:

import os
from werkzeug 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 during development because a standalone media server is not required. One can also mount files on the root folder and still continue to use the application because the shared data middleware forwards all unhandled requests to the application, even if the requests are below one of the shared folders.

If pkg_resources is available you can also tell the middleware to serve files from package data:

app = SharedDataMiddleware(app, {
    '/shared': ('myapplication', 'shared_files')
})

This will then serve the shared_files folder in the myapplication python package.

class DispatcherMiddleware

Allows one to mount middlewares or application in a WSGI application. This is useful if you want to combine multiple WSGI applications:

app = DispatcherMiddleware(app, {
    '/app2':        app2,
    '/app3':        app3
})
class FileStorage

The FileStorage object 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().

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.
__init__ (stream=None, filename=None, name=None, content_type='application/octet-stream', content_length=-1)

Creates a new FileStorage object. The constructor looked different for Werkzeug 0.1 but there the object was only used internally.

Parameters

stream: the input stream for uploaded file. Usually this points to a temporary file.

filename: The filename of the file on the client.

name: the name of the form field

content_type: the content type of the file

content_length: the content length of the file.

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 the memory during the copy process. It defaults to 16KB.
get_host (environ)
Return the real host for the given WSGI enviornment. This takes care of the X-Forwarded-Host header.
get_current_url (environ, root_only=False, strip_querystring=False, host_only=False)

A handy helper function that recreates the full URL for the current request or parts of it. Here an example:

>>> env = create_environ("/?param=foo", "http://localhost/script")
>>> get_current_url(env)
'http://localhost/script/?param=foo'
>>> get_current_url(env, root_only=True)
'http://localhost/script/'
>>> get_current_url(env, host_only=True)
'http://localhost/'
>>> get_current_url(env, strip_querystring=True)
'http://localhost/script/'
responder (f)

Marks a function as responder. Decorate a function with it and it will automatically call the return value as WSGI application.

Example:

@responder
def application(environ, start_response):
    return Response('Hello World!')
create_environ (path='/', base_url=None, query_string=None, method='GET', input_stream=None, content_type=None, content_length=0, errors_stream=None, multithread=False, multiprocess=False, run_once=False)

Create a new WSGI environ dict based on the values passed. The first parameter should be the path of the request which defaults to ‘/’. The second one can either be a absolute path (in that case the URL host is localhost:80) or a full path to the request with scheme, netloc port and the path to the script.

If the path contains a query string it will be used, even if the query_string parameter was given. If it does not contain one the query_string parameter is used as querystring. In that case it can either be a dict, MultiDict or string.

The following options exist:

method
The request method. Defaults to GET
input_stream
The input stream. Defaults to an empty read only stream.
content_type
The content type for this request. Default is an empty content type.
content_length
The value for the content length header. Defaults to 0.
errors_stream
The wsgi.errors stream. Defaults to sys.stderr.
multithread
The multithreaded flag for the WSGI Environment. Defaults to False.
multiprocess
The multiprocess flag for the WSGI Environment. Defaults to False.
run_once
The run_once flag for the WSGI Environment. Defaults to False.
run_wsgi_app (app, environ, buffered=False)

Return a tuple in the form (app_iter, status, headers) of the application output. This works best if you pass it an application that returns a iterator all the time.

Sometimes applications may use the write() callable returned by the start_response function. This tries to resolve such edge cases automatically. But if you don’t get the expected output you should set buffered to True which enforces buffering.

If passed an invalid WSGI application the behavior of this function is undefined. Never pass non-conforming WSGI applications to this function.

Helper Functions

cached_property (func, name=None, doc=None)

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):

    @cached_property
    def foo(self):
        # calculate something important here
        return 42
environ_property (name, default=None, load_func=None, dump_func=None, read_only=False, doc=None)

Maps request attributes to environment variables. This works not only for the Werzeug request object, but also any other class with an environ attribute:

>>> class test_p(object):
...     environ = { 'test': 'test' }
...     test = environ_property('test')
>>> var = test_p()
>>> var.test
test

If you pass it a second value it’s used as default if the key does not exist, the third one can be a converter that takes a value and converts it. If it raises ValueError or TypeError the default value is used. If no default value is provided None is used.

Per default the property works in two directions, but if you set read_only to False it will block set/delete.

header_property (name, default=None, load_func=None, dump_func=None, read_only=False, doc=None)
Like environ_property but for headers.
cookie_date (expires=None, _date_delim='-')

Formats the time to ensure compatibility with Netscape’s cookie standard.

Accepts a floating point number expressed in seconds since the epoc in, a datetime object or a timetuple. All times in UTC. The parse_date function in werkzeug.http can be used to parse such a date.

Outputs a string in the format Wdy, DD-Mon-YYYY HH:MM:SS GMT.

http_date (timestamp=None)

Formats the time to match the RFC1123 date format.

Accepts a floating point number expressed in seconds since the epoc in, a datetime object or a timetuple. All times in UTC. The parse_date function in werkzeug.http can be used to parse such a date.

Outputs a string in the format Wdy, DD Mon YYYY HH:MM:SS GMT.

parse_cookie (header, charset='utf-8')
Parse a cookie. Either from a string or WSGI environ.
dump_cookie (key, value='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=False, charset='utf-8', sync_expires=True)

Creates a new Set-Cookie header without the Set-Cookie prefix The parameters are the same as in the cookie Morsel object in the Python standard library but it accepts unicode data too.

Parameters

max_age: should be a number of seconds, or None (default) if the cookie should last only as long as the client’s browser session. Additionally timedelta objects are accepted too.

expires: should be a datetime object or unix timestamp.

path: limits the cookie to a given path, per default it will span the whole domain.

domain: Use this if you want to set a cross-domain cookie. For example, domain=".example.com" will set a cookie that is readable by the domain www.example.com, foo.example.com etc. Otherwise, a cookie will only be readable by the domain that set it.

secure: The cookie will only be available via HTTPS

httponly: disallow JavaScript to access the cookie. This is an extension to the cookie standard and probably not supported by all browsers.

charset: the encoding for unicode values.

sync_expires: automatically set expires if max_age is defined but expires not.

redirect (location, code=302)
Return a response object (a WSGI application) that, if called, redirects the client to the target location. Supported codes are 301, 302, 303, 305, and 307. 300 is not supported because it’s not a real redirect and 304 because it’s the answer for a request with a request with defined If-Modified-Since headers.
append_slash_redirect (environ, code=301)
Redirect to the same URL but with a slash appended. The behavior of this function is undefined if the path ends with a slash already.
import_string (import_name, silent=False)

Imports an object based on a string. This use useful if you want to use import paths as endpoints or something similar. An import path can be specified either in dotted notation (xml.sax.saxutils.escape) or with a colon as object delimiter (xml.sax.saxutils:escape).

If the silent is True the return value will be None if the import fails.

returns: imported object

find_modules (import_path, include_packages=False, recursive=False)

Find all the modules below a package. This can be useful to automatically import all views / controllers so that their metaclasses / function decorators have a chance to register themselves on the application.

Packages are not returned unless include_packages is True. This can also recursively list modules but in that case it will import all the packages to get the correct load path of that module.

returns: generator

test_app (environ, start_response)
Simple test application that dumps the environment.