Werkzeug

Utilities

You can import all these objects directly from werkzeug.

Middlewares

class werkzeug.SharedDataMiddleware(app, exports, disallow=None, cache=True, cache_timeout=43200)

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.

The optional disallow parameter can be a list of fnmatch rules for files that are not accessible from the web. If cache is set to False no caching headers are sent.

Currently the middleware does not support non ASCII filenames. If the encoding on the file system happens to be the encoding of the URI it may work but this could also be by accident. We strongly suggest using ASCII only file names for static files.

Changed in version 0.5: The cache timeout is configurable now.

Parameters:
  • app – the application to wrap. If you don’t want to wrap an application you can pass it NotFound.
  • exports – a dict of exported files and folders.
  • diallow – a list of fnmatch rules.
  • cache – enable or disable caching headers.
Param cache_timeout:
 

the cache timeout in seconds for the headers.

is_allowed(filename)
Subclasses can override this method to disallow the access to certain files. However by providing disallow in the constructor this method is overwritten.
class werkzeug.DispatcherMiddleware(app, mounts=None)

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

WSGI Helpers

class werkzeug.ClosingIterator(iterable, callbacks=None)

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 passed instead of the list.

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

try:
    return response(environ, start_response)
finally:
    cleanup_session()
    cleanup_locals()
class werkzeug.FileWrapper(file, buffer_size=8192)

This class can be used to convert a file-like object into an iterable. It yields buffer_size blocks until the file is fully read.

You should not use this class directly but rather use the wrap_file function that uses the WSGI server’s file wrapper support if it’s available.

New in version 0.5.

Parameters:
  • file – a file-like object with a read method.
  • buffer_size – number of bytes for one iteration.
class werkzeug.LimitedStream(stream, limit, silent=True)

Wraps a stream so that it doesn’t read more than n bytes. If the stream is exhausted and the caller tries to get more bytes from it on_exhausted is called which by default returns an empty string or raises BadRequest if silent is set to False. The return value of that function is forwarded to the reader function. So if it returns an empty string read will return an empty string as well.

The limit however must never be higher than what the stream can output. Otherwise readlines will try to read past the limit.

The silent parameter has no effect if is_exhausted is overriden by a subclass.

Note on WSGI compliance

calls to readline and readlines are not WSGI compliant because it passes a size argument to the readline methods. Unfortunately the WSGI PEP is not safely implementable without a size argument to readline because there is no EOF marker in the stream. As a result of that the use of readline is discouraged.

For the same reason iterating over the LimitedStream is not portable. It internally calls readline.

We strongly suggest using read only or using the make_line_iter which savely iterates line-based over a WSGI input stream.

Parameters:
  • stream – the stream to wrap.
  • limit – the limit for the stream, must not be longer than what the string can provide if the stream does not end with EOF (like wsgi.input)
  • silent – If set to True the stream will allow reading past the limit and will return an empty string.
exhaust(chunk_size=16384)

Exhaust the stream. This consumes all the data left until the limit is reached.

Parameter:chunk_size – the size for a chunk. It will read the chunk until the stream is exhausted and throw away the results.
is_exhausted
If the stream is exhausted this attribute is True.
on_exhausted()

This is called when the stream tries to read past the limit. The return value of this function is returned from the reading function.

Per default this raises a BadRequest.

read(size=None)

Read size bytes or if size is not provided everything is read.

Parameter:size – the number of bytes read.
readline(size=None)
Reads one line from the stream.
readlines(size=None)
Reads a file into a list of strings. It calls readline until the file is read to the end. It does support the optional size argument if the underlaying stream supports it for readline.
werkzeug.make_line_iter(stream, limit=None, buffer_size=10240)

Savely iterates line-based over an input stream. If the input stream is not a LimitedStream the limit parameter is mandatory.

This uses the stream’s read method internally as opposite to the readline method that is unsafe and can only be used in violation of the WSGI specification. The same problem applies to the __iter__ function of the input stream which calls readline without arguments.

If you need line-by-line processing it’s strongly recommended to iterate over the input stream using this helper function.

Parameters:
  • stream – the stream to iterate over.
  • limit – the limit in bytes for the stream. (Usually content length. Not necessary if the stream is a LimitedStream.
  • buffer_size – The optional buffer size.
werkzeug.get_host(environ)

Return the real host for the given WSGI environment. This takes care of the X-Forwarded-Host header.

Parameter:environ – the WSGI environment to get the host of.
werkzeug.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/'
Parameters:
  • environ – the WSGI environment to get the current URL from.
  • root_only – set True if you only want the root URL.
  • strip_querystring – set to True if you don’t want the querystring.
  • host_only – set to True if the host URL should be returned.
werkzeug.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!')
werkzeug.test_app(environ, start_response)
Simple test application that dumps the environment.
werkzeug.wrap_file(environ, file, buffer_size=8192)

Wraps a file. This uses the WSGI server’s file wrapper if available or otherwise the generic FileWrapper.

New in version 0.5.

If the file wrapper from the WSGI server is used it’s important to not iterate over it from inside the application but to pass it through unchanged. If you want to pass out a file wrapper inside a response object you have to set direct_passthrough to True.

More information about file wrappers are available in PEP 333.

Parameters:
  • file – a file-like object with a read method.
  • buffer_size – number of bytes for one iteration.
werkzeug.pop_path_info(environ)

Removes and returns the next segment of PATH_INFO, pushing it onto SCRIPT_NAME. Returns None if there is nothing left on PATH_INFO.

If there are empty segments ('/foo//bar) these are ignored but properly pushed to the SCRIPT_NAME:

>>> env = {'SCRIPT_NAME': '/foo', 'PATH_INFO': '/a/b'}
>>> pop_path_info(env)
'a'
>>> env['SCRIPT_NAME']
'/foo/a'
>>> pop_path_info(env)
'b'
>>> env['SCRIPT_NAME']
'/foo/a/b'

New in version 0.5.

Parameter:environ – the WSGI environment that is modified.
werkzeug.peek_path_info(environ)

Returns the next segment on the PATH_INFO or None if there is none. Works like pop_path_info without modifying the environment:

>>> env = {'SCRIPT_NAME': '/foo', 'PATH_INFO': '/a/b'}
>>> peek_path_info(env)
'a'
>>> peek_path_info(env)
'a'

New in version 0.5.

Parameter:environ – the WSGI environment that is checked.
werkzeug._easteregg(app)
Like the name says. But who knows how it works?

URL Helpers

class werkzeug.Href(base='./', charset='utf-8', sort=False, key=None)

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 version 0.5: sort and key were added.

werkzeug.url_decode(s, charset='utf-8', decode_keys=False, include_empty=True, errors='ignore', separator='&', cls=None)

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 ignored. If you want a different behavior you can set errors to 'replace' or 'strict'. In strict mode a HTTPUnicodeError is raised.

Changed in version 0.5: In previous versions “;” and “&” could be used for url decoding. This changed in 0.5 where only “&” is supported. If you want to use “;” instead a different separator can be provided.

The cls parameter was added.

Parameters:
  • s – a string with the query string to decode.
  • charset – the charset of the query string.
  • decode_keys – set to True if you want the keys to be decoded as well.
  • include_empty – Set to False if you don’t want empty values to appear in the dict.
  • errors – the decoding error behavior.
  • separator – the pair separator to be used, defaults to &
  • cls – an optional dict class to use. If this is not specified or None the default MultiDict is used.
werkzeug.url_encode(obj, charset='utf-8', encode_keys=False, sort=False, key=None, separator='&')

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 version 0.5: sort, key, and separator were added.

Parameters:
  • obj – the object to encode into a query string.
  • charset – the charset of the query string.
  • encode_keys – set to True if you have unicode keys.
  • sort – set to True if you want parameters to be sorted by key.
  • separator – the separator to be used for the pairs.
  • key – an optional function to be used for sorting. For more details check out the sorted documentation.
werkzeug.url_quote(s, charset='utf-8', safe='/:')

URL encode a single string with a given encoding.

Parameters:
  • s – the string to quote.
  • charset – the charset to be used.
  • safe – an optional sequence of safe characters.
werkzeug.url_quote_plus(s, charset='utf-8', safe='')

URL encode a single string with the given encoding and convert whitespace to “+”.

Parameters:
  • s – the string to quote.
  • charset – the charset to be used.
  • safe – an optional sequence of safe characters.
werkzeug.url_unquote(s, charset='utf-8', errors='ignore')

URL decode a single string with a given decoding.

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

Parameters:
  • s – the string to unquote.
  • charset – the charset to be used.
  • errors – the error handling for the charset decoding.
werkzeug.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 ignored. If you want a different behavior you can set errors to 'replace' or 'strict'. In strict mode a HTTPUnicodeError is raised.

Parameters:
  • s – the string to unquote.
  • charset – the charset to be used.
  • errors – the error handling for the charset decoding.
werkzeug.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\xe4rung)')
'http://de.wikipedia.org/wiki/Elf%20%28Begriffskl%C3%A4rung%29'
Parameters:
  • s – the string with the URL to fix.
  • charset – The target charset for the URL if the url was given as unicode string.

HTML Helpers

class werkzeug.HTMLBuilder(dialect)

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')])
u'<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>"))
u'<p>&lt;foo&gt;</p>'
werkzeug.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.

Parameters:
  • s – the string to escape.
  • quote – set to true to also escape double quotes.
werkzeug.unescape(s)

The reverse function of escape. This unescapes all the HTML entities, not only the XML entities inserted by escape.

Parameter:s – the string to unescape.

HTTP Helpers

class werkzeug.UserAgent(environ_or_string)

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

string
the raw user agent string
platform

the browser platform. The following platforms are currently recognized:

  • aix
  • amiga
  • android
  • bsd
  • hpux
  • iphone
  • irix
  • linux
  • macos
  • sco
  • solaris
  • wii
  • windows
browser

the name of the browser. The following browsers are currently recognized:

  • aol *
  • ask *
  • camino
  • chrome
  • firefox
  • galeon
  • google *
  • kmeleon
  • konqueror
  • links
  • lynx
  • msie
  • msn
  • netscape
  • opera
  • safari
  • seamonkey
  • webkit
  • yahoo *

(Browsers maked with a star (*) are crawlers.)

version
the version of the browser
language
the language of the browser
werkzeug.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.

Parameters:
  • iterable – the iterable or dict of values to quote.
  • allow_token – if set to False tokens as values are disallowed. See quote_header_value for more details.
werkzeug.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 can be used to parse such a date.

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

Parameter:expires – If provided that date is used, otherwise the current.
werkzeug.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 can be used to parse such a date.

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

Parameter:timestamp – If provided that date is used, otherwise the current.
werkzeug.parse_form_data(environ, stream_factory=None, charset='utf-8', errors='ignore', max_form_memory_size=None, max_content_length=None, cls=None, silent=True)

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 unknown the input stream is wrapped and returned as first argument, else the stream is empty.

This function does not raise exceptions, even if the input data is malformed.

Have a look at Dealing with Request Data for more details.

New in version 0.5: The max_form_memory_size, max_content_length and cls parameters were added.

New in version 0.5.1: The optional silent flag was added.

Parameters:
  • environ – the WSGI environment to be used for parsing.
  • stream_factory – An optional callable that returns a new read and writeable file descriptor. This callable works the same as _get_file_stream.
  • charset – The character set for URL and url encoded form data.
  • errors – The encoding error behavior.
  • max_form_memory_size – the maximum number of bytes to be accepted for in-memory stored form data. If the data exceeds the value specified an RequestURITooLarge exception is raised.
  • max_content_length – If this is provided and the transmitted data is longer than this value an RequestEntityTooLarge exception is raised.
  • cls – an optional dict class to use. If this is not specified or None the default MultiDict is used.
  • silent – If set to False parsing errors will not be catched.
Returns:

A tuple in the form (stream, form, files).

werkzeug.parse_etags(value)

Parse an etag header.

Parameter:value – the tag header to parse
Returns:an ETags object.
werkzeug.quote_etag(etag, weak=False)

Quote an etag.

Parameters:
  • etag – the etag to quote.
  • weak – set to True to tag it “weak”.
werkzeug.unquote_etag(etag)

Unquote a single etag:

>>> unquote_etag('w/"bar"')
('bar', True)
>>> unquote_etag('"bar"')
('bar', False)
Parameter:etag – the etag identifier to unquote.
Returns:a (etag, weak) tuple.
werkzeug.generate_etag(data)
Generate an etag for some data.
werkzeug.is_resource_modified(environ, etag=None, data=None, last_modified=None)

Convenience method for conditional requests.

Parameters:
  • environ – the WSGI environment of the request to be checked.
  • etag – the etag for the response for comparision.
  • data – or alternatively the data of the response to automatically generate an etag using generate_etag.
  • last_modified – an optional date of the last modification.
Returns:

True if the resource was modified, otherwise False.

werkzeug.parse_options_header(value)

Parse a Content-Type like header into a tuple with the content type and the options:

>>> parse_options_header('Content-Type: text/html; mimetype=text/html')
('Content-Type: text/html', {'mimetype': 'text/html'})

This should not be used to parse Cache-Control like headers that use a slightly different format. For these headers use the parse_dict_header function.

New in version 0.5.

Parameter:value – the header to parse.
Returns:(str, options)
werkzeug.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-insensitively and keeps the order of the items.

Parameters:
  • value – a set header to be parsed.
  • on_update – an optional callable that is called every time a value on the HeaderSet object is changed.
Returns:

a HeaderSet

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

Parameter:value – a string with a list header.
Returns:list
werkzeug.parse_dict_header(value)

Parse lists of key, value pairs 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.

Parameter:value – a string with a dict header.
Returns:dict
werkzeug.parse_accept_header(value[, class])

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 (basically a list of (value, quality) tuples sorted by the quality with some additional accessor methods).

The second parameter can be a subclass of Accept that is created with the parsed values and returned.

Parameters:
  • value – the accept header string to be parsed.
  • cls – the wrapper class for the return value (can be Accept or a subclass thereof)
Returns:

an instance of cls.

werkzeug.parse_cache_control_header(value, on_update=None, cls=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.

New in version 0.5: The cls was added. If not specified an immutable RequestCacheControl is returned.

Parameters:
  • value – a cache control header to be parsed.
  • on_update – an optional callable that is called every time a value on the CacheControl object is changed.
  • cls – the class for the returned object. By default RequestCacheControl is used.
Returns:

a cls object.

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

Parameter:value – a string with a supported date format.
Returns:a datetime.datetime object.
werkzeug.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.

Parameter:value – the authorization header to parse.
Returns:a Authorization object or None.
werkzeug.parse_www_authenticate_header(value, on_update=None)

Parse an HTTP WWW-Authenticate header into a WWWAuthenticate object.

Parameters:
  • value – a WWW-Authenticate header to parse.
  • on_update – an optional callable that is called every time a value on the WWWAuthenticate object is changed.
Returns:

a WWWAuthenticate object.

werkzeug.remove_entity_headers(headers, allowed=('expires', 'content-location'))

Remove all entity headers from a list or Headers object. This operation works in-place. Expires and Content-Location headers are by default not removed. The reason for this is RFC 2616 section 10.3.5 which specifies some entity headers that should be sent.

Changed in version 0.5: added allowed parameter.

Parameters:
  • headers – a list or Headers object.
  • allowed – a list of headers that should still be allowed even though they are entity headers.
werkzeug.remove_hop_by_hop_headers(headers)

Remove all HTTP/1.1 “Hop-by-Hop” headers from a list or Headers object. This operation works in-place.

New in version 0.5.

Parameter:headers – a list or Headers object.
werkzeug.is_entity_header(header)

Check if a header is an entity header.

New in version 0.5.

Parameter:header – the header to test.
Returns:True if it’s an entity header, False otherwise.
werkzeug.is_hop_by_hop_header(header)

Check if a header is an HTTP/1.1 “Hop-by-Hop” header.

New in version 0.5.

Parameter:header – the header to test.
Returns:True if it’s an entity header, False otherwise.
werkzeug.quote_header_value(value, extra_chars='', allow_token=True)

Quote a header value if necessary.

New in version 0.5.

Parameters:
  • value – the value to quote.
  • extra_chars – a list of extra characters to skip quoting.
  • allow_token – if this is enabled token values are returned unchanged.
werkzeug.unquote_header_value(value)

Unquotes a header value. (Reversal of quote_header_value). This does not use the real unquoting but what browsers are actually using for quoting.

New in version 0.5.

Parameter:value – the header value to unquote.
werkzeug.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.

General Helpers

class werkzeug.cached_property(func, name=None, doc=None, writeable=False)

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

Changed in version 0.5: cached properties are now optionally writeable.

class werkzeug.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(object):
...     environ = {'key': 'value'}
...     test = environ_property('key')
>>> var = Test()
>>> var.test
'value'

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.

class werkzeug.header_property(name, default=None, load_func=None, dump_func=None, read_only=None, doc=None)
Like environ_property but for headers.

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

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

Changed in version 0.5: This function now returns a TypeConversionDict instead of a regular dict. The cls parameter was added.

Parameters:
  • header – the header to be used to parse the cookie. Alternatively this can be a WSGI environment.
  • charset – the charset for the cookie values.
  • errors – the error behavior for the charset decoding.
  • cls – an optional dict class to use. If this is not specified or None the default TypeConversionDict is used.

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

Parameters:
  • location – the location the response should redirect to.
  • code – the redirect status code.
werkzeug.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.

Parameters:
  • environ – the WSGI environment for the request that triggers the redirect.
  • code – the status code for the redirect.
werkzeug.import_string(import_name, silent=False)

Imports an object based on a string. This is 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 silent is True the return value will be None if the import fails.

Parameters:
  • import_name – the dotted name for the object to import.
  • silent – if set to True import errors are ignored and None is returned instead.
Returns:

imported object

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

Parameters:
  • import_name – the dotted name for the package to find child modules.
  • include_packages – set to True if packages should be returned, too.
  • recursive – set to True if recursion should happen.
Returns:

generator

werkzeug.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
Parameters:
  • func – the function the validation is performed against.
  • args – a tuple of positional arguments.
  • kwargs – a dict of keyword arguments.
  • drop_extra – set to False if you don’t want extra arguments to be silently dropped.
Returns:

tuple in the form (args, kwargs).

werkzeug.secure_filename(filename)

Pass it a filename and it will return a secure version of it. This filename can then savely be stored on a regular file system and passed to os.path.join. The filename returned is an ASCII only string for maximum portability.

On windows system the function also makes sure that the file is not named after one of the special device files.

>>> secure_filename("My cool movie.mov")
'My_cool_movie.mov'
>>> secure_filename("../../../etc/passwd")
'etc_passwd'
>>> secure_filename(u'i contain cool \xfcml\xe4uts.txt')
'i_contain_cool_umlauts.txt'

New in version 0.5.

Parameter:filename – the filename to secure
werkzeug.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.

Parameters:
  • func – the function the arguments should be bound for.
  • args – tuple of positional arguments.
  • kwargs – a dict of keyword arguments.
Returns:

a dict of bound keyword arguments.