circuits.web.headers module

Headers Support

This module implements support for parsing and handling headers.

circuits.web.headers.header_elements(fieldname, fieldvalue)

Return a sorted HeaderElement list.

Returns a sorted HeaderElement list from a comma-separated header string.

class circuits.web.headers.HeaderElement(value, params=None)

Bases: object

An element (with parameters) from an HTTP header’s element list.

static parse(elementstr)

Transform ‘token;key=val’ to (‘token’, {‘key’: ‘val’}).

classmethod from_str(elementstr)

Construct an instance from a string of the form ‘token;key=val’.

class circuits.web.headers.AcceptElement(value, params=None)

Bases: HeaderElement

An element (with parameters) from an Accept* header’s element list.

AcceptElement objects are comparable; the more-preferred object will be “less than” the less-preferred object. They are also therefore sortable; if you sort a list of AcceptElement objects, they will be listed in priority order; the most preferred value will be first. Yes, it should have been the other way around, but it’s too late to fix now.

classmethod from_str(elementstr)

Construct an instance from a string of the form ‘token;key=val’.

property qvalue

The qvalue, or priority, of this value.

class circuits.web.headers.CaseInsensitiveDict(*args, **kwargs)

Bases: dict

A case-insensitive dict subclass.

Each key is changed on entry to str(key).title().

get(key, default=None)

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

classmethod fromkeys(seq, value=None)

Create a new dictionary with keys from iterable and values set to value.

setdefault(key, x=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

class circuits.web.headers.Headers(*args, **kwargs)

Bases: CaseInsensitiveDict

This class implements a storage for headers as key value pairs. The underlying model of a case insensitive dict matches the requirements for headers quite well, because usually header keys are unique. If several values may be associated with a header key, most HTTP headers represent the values as an enumeration using a comma as item separator.

There is, however one exception (currently) to this rule. In order to set several cookies, there should be multiple headers with the same key, each setting one cookie (“Set-Cookie: some_cookie”).

This is modeled by having either a string (common case) or a list (cookie case) as value in the underlying dict. In order to allow easy iteration over all headers as they appear in the HTTP request, the items() method expands associated lists of values. So if you have { “Set-Cookie”: [ “cookie1”, “cookie2” ] }, the items() method returns the two pairs (“Set-Cookie”, “cookie1”) and (“Set-Cookie”, “cookie2”). This is convenient for most use cases. The only drawback is that len(keys()) is not equal to len(items()) for this specialized dict.

elements(key)

Return a sorted list of HeaderElements for the given header.

get_all(name)

Return a list of all the values for the named field.

items() → a set-like object providing a view on D's items

append(key, value)

If a header with the given name already exists, the value is normally appended to the existing value separated by a comma.

If, however, the already existing entry associated key with a value of type list (as is the case for “Set-Cookie”), the new value is appended to that list.

add_header(_name, _value, **_params)

Extended header setting.

_name is the header field to add. keyword arguments can be used to set additional parameters for the header field, with underscores converted to dashes. Normally the parameter will be added as key=”value” unless value is None, in which case only the key will be added.

Example:

h.add_header(‘content-disposition’, ‘attachment’, filename=’bud.gif’)

Note that unlike the corresponding ‘email.Message’ method, this does not handle ‘(charset, language, value)’ tuples: all values must be strings or None.