Navigation

Werkzeug provides a couple of functions to parse and generate HTTP headers
that are useful when implementing WSGI middlewares or whenever you are
operating on a lower level layer. All this functionality is also exposed
from request and response objects.

The following functions simplify working with times in an HTTP context.
Werkzeug uses offset-naive datetime objects internally
that store the time in UTC. If you’re working with timezones in your
application make sure to replace the tzinfo attribute with a UTC timezone
information before processing the values.

The following functions can be used to parse incoming HTTP headers.
Because Python does not provide data structures with the semantics required
by RFC 2616, Werkzeug implements some custom data structures that are
documented separately.

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.

It basically works like parse_set_header() just that items
may appear multiple times and case sensitivity is preserved.

Parse lists of key, value pairs as described by RFC 2068 Section 2 and
convert them into a python dict (or any other mapping object created from
the type with a dict like interface provided by the cls arugment):

The following utilities operate on HTTP headers well but do not parse
them. They are useful if you’re dealing with conditional responses or if
you want to proxy arbitrary requests but want to remove WSGI-unsupported
hop-by-hop headers. Also there is a function to create HTTP header
strings from the parsed data.

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.

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.

On Python 3 the return value of this function will be a unicode
string, on Python 2 it will be a native string. In both cases the
return value is usually restricted to ascii as the vast majority of
values are properly escaped, but that is no guarantee. If a unicode
string is returned it’s tunneled through latin1 as required by
PEP 3333.

The return value is not ASCII safe if the key contains unicode
characters. This is technically against the specification but
happens in the wild. It’s strongly recommended to not use
non-ASCII values for the keys.

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.

Normally the WSGI environment is provided by the WSGI gateway with the
incoming data as part of it. If you want to generate such fake-WSGI
environments for unittesting you might want to use the
create_environ() function or the EnvironBuilder instead.

This class implements parsing of form data for Werkzeug. By itself
it can parse multipart and url encoded form data. It can be subclassed
and extended but for most mimetypes it is a better idea to use the
untouched stream and expose it as separate attributes on a request
object.

New in version 0.8.

Parameters:

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

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, PUT, or PATCH.

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.