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.

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.

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.

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

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.

__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, **_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')

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

pop (key=None, default=<object object at 0x274b8>)
Removes a key or index.
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.
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.

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.

Working with HTTP Headers

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.
parse_list_header (value)

Parse lists as described by RFC 2068 Section 2.

In particular, parse comma-separated lists where the elements of the list may include quoted-strings. A quoted-string could contain a comma. A non-quoted string could have quotes in the middle. Quotes are removed automatically after parsing.

parse_dict_header (value)
Parse lists of key, value paits as described by RFC 2068 Section 2 and convert them into a python dict. If there is no value for a key it will be None.
dump_header (iterable, allow_token=True)

Dump an HTTP header again. This is the reversal of parse_list_header, parse_set_header and parse_dict_header. This also quotes strings that include an equals sign unless you pass it as dict of key, value pairs.

The allow_token parameter can be set to False to disallow tokens as values. If this is enabled all values are quoted.

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

The behavior of this class changed slightly from 0.3 to 0.4. Since 0.4 setting no_cache or private to boolean True will set the implicit none-value which is *:

>>> cc = CacheControl()
>>> cc.no_cache = True
>>> cc
<CacheControl 'no-cache'>
>>> cc.no_cache
'*'
>>> cc.no_cache = None
>>> cc
<CacheControl ''>
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.
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.

cookie_date (expires=None)

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_form_data (environ, stream_factory=None, charset='utf-8', errors='ignore')

Parse the form data in the environ and return it as tuple in the form (stream, form, files). You should only call this method if the transport method is POST or PUT.

If the mimetype of the data transmitted is multipart/form-data the files multidict will be filled with FileStorage objects. If the mimetype is unknow the input stream is wrapped and returned as first argument, else the stream is empty.

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

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.

to_header ()
Convert the stored values into a WWW-Authenticate header.
username
The username transmitted. This is set for both basic and digest auth all the time.
password
When the authentication type is basic this is the password transmitted by the client, else None.
realm
This is the server realm send back for digest auth. For HTTP digest auth.
nonce
The nonce the server send for digest auth, send back by the client. A nonce should be unique for every 401 response for HTTP digest auth.
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.
nc
The nonce count value transmitted by clients if a qop-header is also transmitted. HTTP digest auth only.
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.
response
A string of 32 hex digits computed as defined in RFC 2617, which proves that the user knows a password. Digest auth only.
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.
qop
Indicates what “quality of protection” the client has applied to the message for HTTP digest auth.
class WWWAuthenticate

Provides simple access to WWW-Authenticate headers.

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.
to_header ()
Convert the stored values into a WWW-Authenticate header.
type
The type of the auth machanism. HTTP currently specifies Basic and Digest.
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.
stale
A flag, indicating that the previous request from the client was rejected because the nonce value was stale.
domain
A list of URIs that define the protection space. If a URI is an absolte 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.
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).
qop
A set of quality-of-privacy modifies such as auth and auth-int.
parse_authorization_header (value)
Parse an HTTP basic/digest authorization header transmitted by the web browser. The return value is either None if the header was invalid or not given, otherwise an Authorization object.
parse_www_authenticate_header (value, on_update=None)
Parse an HTTP WWW-Authenticate header into a WWWAuthenticate object.
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, errors='ignore')

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.

Per default encoding errors are ignore. If you want a different behavior you can set errors to 'replace' or 'strict'. In strict mode a HTTPUnicodeError is raised.

url_encode (obj, charset='utf-8', encode_keys=False, sort=False, key=None)

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.

If sort is set to True the items are sorted by key or the default sorting algorithm.

new in Werkzeug 0.5: sort and key were added.

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', errors='ignore')

URL decode a single string with a given decoding.

Per default encoding errors are ignore. If you want a different behavior you can set errors to 'replace' or 'strict'. In strict mode a HTTPUnicodeError is raised.

url_unquote_plus (s, charset='utf-8', errors='ignore')

URL decode a single string with the given decoding and decode a “+” to whitespace.

Per default encoding errors are ignore. If you want a different behavior you can set errors to 'replace' or 'strict'. In strict mode a HTTPUnicodeError is raised.

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'
>>> href({'foo': 'bar'})
'/foo?foo=bar'

Combining of both methods is not allowed:

>>> href({'foo': 'bar'}, bar=42)
Traceback (most recent call last):
  ...
TypeError: keyword arguments and query-dicts can't be combined

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'

If sort is set to True the items are sorted by key or the default sorting algorithm:

>>> href = Href("/", sort=True)
>>> href(a=1, b=2, c=3)
'/?a=1&b=2&c=3'

new in Werkzeug 0.5: sort and key were added.

HTML Helpers

escape (s, quote=False)

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.

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 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=None, 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 is read only. You have to explicitly enable it by passing read_only=False to the constructor.

header_property (name, default=None, load_func=None, dump_func=None, read_only=None, doc=None)
Like environ_property but for headers.
parse_cookie (header, charset='utf-8', errors='ignore')

Parse a cookie. Either from a string or WSGI environ.

Per default encoding errors are ignore. If you want a different behavior you can set errors to 'replace' or 'strict'. In strict mode a HTTPUnicodeError is raised.

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

validate_arguments (func, args, kwargs, drop_extra=True)

Check if the function accepts the arguments and keyword arguments. Returns a new (args, kwargs) tuple that can savely be passed to the function without causing a TypeError because the function signature is incompatible. If drop_extra is set to True (which is the default) any extra positional or keyword arguments are dropped automatically.

The exception raised provides three attributes:

missing
A set of argument names that the function expected but where missing.
extra
A dict of keyword arguments that the function can not handle but where provided.
extra_positional
A list of values that where given by positional argument but the function cannot accept.

This can be useful for decorators that forward user submitted data to a view function:

from werkzeug import ArgumentValidationError, validate_arguments

def sanitize(f):
    def proxy(request):
        data = request.values.to_dict()
        try:
            args, kwargs = validate_arguments(f, (request,), data)
        except ArgumentValidationError:
            raise BadRequest('The browser failed to transmit all '
                             'the data expected.')
        return f(*args, **kwargs)
    return proxy
bind_arguments (func, args, kwargs)
Bind the arguments provided into a dict. When passed a function, a tuple of arguments and a dict of keyword arguments bind_arguments returns a dict of names as the function would see it. This can be useful to implement a cache decorator that uses the function arguments to build the cache key based on the values of the arguments.
test_app (environ, start_response)
Simple test application that dumps the environment.