circuits.web.headers module

Headers Support

This module implements support for parsing and handling headers.

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

Bases: circuits.web.headers.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)

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

classmethod fromkeys(seq, value=None)

get(key, default=None)

pop(key, default=None)

setdefault(key, x=None)

update(E)

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

Bases: object

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

classmethod from_str(elementstr)

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

static parse(elementstr)

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

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

Bases: circuits.web.headers.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.

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.

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.

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

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

Return a sorted HeaderElement list.

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