The Swiss Army Knife For Python Web Developers
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.
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:
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
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
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']
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.
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.
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.
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.
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.
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
Convert the headers into a list and converts the unicode header items to the specified charset.
returns: list
All the other dict functions such as iterkeys are available and work the same.
An Accept object is just a list subclass for lists of (value, quality) tuples. It is automatically sorted by quality.
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)
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
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'])
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.
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:
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.
A set that can be used to check if one etag is present in a collection of etags.
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.
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'
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'
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.
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><foo></p>'
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()
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.
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 })
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().
Creates a new FileStorage object. The constructor looked different for Werkzeug 0.1 but there the object was only used internally.
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.
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/'
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 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:
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.
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
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.
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.
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.
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.
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.
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 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