5.4. HTTP Protocol Parameters

This section defines functions for handling basic parameters used by HTTP. Refer to Section 3 of RFC2616 for details.

The approach taken by this module is provide classes for each of the parameter types. Most classes have a class method ‘from_str’ which returns a new instance parsed from a string and performs the reverse transformation to the builtin str function. Instances are generally immutable objects which is consistent with them representing values of parameters in the protocol.

class pyslet.http.params.HTTPVersion(major=1, minor=None)

Bases: object

Represents the HTTP Version.

major
The (optional) major version
minor
The (optional) minor version

The default instance, HTTPVersion(), represents HTTP/1.1

HTTPVersion objects are immutable, they define comparison functions (such that 1.1 > 1.0 and 1.2 < 1.25) and a hash implementation is provided.

On conversion to a string the output is of the form:

HTTP/<major>.<minor>

For convenience, the constants HTTP_1p1 and HTTP_1p0 are provided for comparisons, e.g.:

if HTTPVersion.from_str(version_str) == HTTP_1p0:
    # do something to support a legacy system...
major = None

major protocol version (read only)

minor = None

minor protocol version (read only)

classmethod from_str(source)

Constructs an HTTPVersion object from a string.

class pyslet.http.params.HTTPURL(octets='http://localhost/', host=None, path=None, query=None, fragment=None)

Bases: pyslet.rfc2396.ServerBasedURL

Represents http URLs

DEFAULT_PORT = 80

the default HTTP port

canonicalize()

Returns a canonical form of this URI

class pyslet.http.params.HTTPSURL(octets='https://localhost/')

Bases: pyslet.http.params.HTTPURL

Represents https URLs

DEFAULT_PORT = 443

the default HTTPS port

class pyslet.http.params.FullDate(src=None, date=None, time=None)

Bases: pyslet.iso8601.TimePoint

A special sub-class for HTTP-formatted dates

classmethod from_http_str(source)

Returns an instance parsed from an HTTP formatted string

class pyslet.http.params.TransferEncoding(token='chunked', parameters={})

Bases: object

Represents an HTTP transfer-encoding.

token
The transfer encoding identifier, defaults to “chunked”
parameters
A parameter dictionary mapping parameter names to tuples of strings: (parameter name, parameter value)

The built-in str function can be used to format instances according to the grammar defined in the specification.

Instances are immutable, they define comparison methods and a hash implementation.

token = None

the lower-cased transfer-encoding token (defaults to “chunked”)

parameters = None

declared extension parameters

classmethod from_str(source)

Parses the transfer-encoding from a source string.

If the encoding is not parsed correctly BadSyntax is raised.

classmethod list_from_str(source)

Creates a list of transfer-encodings from a string

Transfer-encodings are comma-separated

class pyslet.http.params.Chunk(size=0, extensions=None)

Bases: object

Represents an HTTP chunk header

size
The size of this chunk (defaults to 0)
extensions
A parameter dictionary mapping parameter names to tuples of strings: (chunk-ext-name, chunk-ext-val)

The built-in str function can be used to format instances according to the grammar defined in the specification. The resulting string does not include the trailing CRLF.

Instances are immutable, they define comparison methods and a hash implementation.

size = None

the chunk-size

classmethod from_str(source)

Parses the chunk header from a source string of TEXT.

If the chunk header is not parsed correctly BadSyntax is raised. The header includes the chunk-size and any chunk-extension parameters but it does not include the trailing CRLF or the chunk-data

class pyslet.http.params.MediaType(type='application', subtype='octet-stream', parameters={})

Bases: object

Represents an HTTP media-type.

The built-in str function can be used to format instances according to the grammar defined in the specification.

type
The type code string, defaults to ‘application’
subtype
The sub-type code, defaults to ‘octet-stream’
parameters
A dictionary such as would be returned by grammar.WordParser.parse_parameters() containing the media type’s parameters.

Instances are immutable and support parameter value access by lower-case key, returning the corresponding value or raising KeyError. E.g., mtype[‘charset’]

Instances also define comparison methods and a hash implementation. Media-types are compared by type, subtype and ultimately parameters.

classmethod from_str(source)

Creates a media-type from a source string.

Enforces the following rule from the specification:

Linear white space (LWS) MUST NOT be used between the type and subtype, nor between an attribute and its value
class pyslet.http.params.ProductToken(token=None, version=None)

Bases: object

Represents an HTTP product token.

The built-in str function can be used to format instances according to the grammar defined in the specification.

Instances are immutable, they define comparison methods and a hash implementation.

The comparison operations use a more interesting sort than plain text on version in order to provide a more intuitive ordering. As it is common practice to use dotted decimal notation for versions (with some alphanumeric modifiers) the version string is exploded (see explode()) internally on construction and this exploded value is used in comparisons. The upshot is that version 1.0.3 sorts before 1.0.10 as you would expect and 1.0a < 1.0 < 1.0.3a3 < 1.0.3a20 < 1.0.3b1 < 1.0.3; there are limits to this algorithm. 1.0dev > 1.0b1 even though it looks like it should be the other way around. Similarly 1.0-live < 1.0-prod etc.

You shouldn’t use this comparison as a definitive way to determine that one release is more recent or up-to-date than another unless you know that the product in question uses a numbering scheme compatible with these rules.

token = None

the product’s token

version = None

the product’s version

classmethod explode(version)

Returns an exploded version string.

Version strings are split by dot and then by runs of non-digit characters resulting in a list of tuples. Examples will help:

explode("2.15")==((2),(15))
explode("2.17b3")==((2),(17,"b",3))
explode("2.b3")==((2),(-1,"b",3))

Note that a missing leading numeric component is treated as -1 to force “a3” to sort before “0a3”.

classmethod from_str(source)

Creates a product token from a source string.

classmethod list_from_str(source)

Creates a list of product tokens from a source string.

Individual tokens are separated by white space.

class pyslet.http.params.LanguageTag(primary, *subtags)

Bases: object

Represents an HTTP language-tag.

The built-in str function can be used to format instances according to the grammar defined in the specification.

Instances are immutable, they define comparison methods and a hash implementation.

partial_match(range)

True if this tag is a partial match against range

range
A tuple of lower-cased subtags. An empty tuple matches all instances.

For example:

lang=LanguageTag("en",("US","Texas"))
lang.partial_match(())==True
lang.partial_match(("en",)==True
lang.partial_match(("en","us")==True
lang.partial_match(("en","us","texas")==True
lang.partial_match(("en","gb")==False
lang.partial_match(("en","us","tex")==False
classmethod from_str(source)

Creates a language tag from a source string.

Enforces the following rules from the specification:

White space is not allowed within the tag
classmethod list_from_str(source)

Creates a list of language tags from a source string.

class pyslet.http.params.EntityTag(tag, weak=True)

Represents an HTTP entity-tag.

tag
The opaque tag
weak
A boolean indicating if the entity-tag is a weak or strong entity tag. Defaults to True.

The built-in str function can be used to format instances according to the grammar defined in the specification.

Instances are immutable, they define comparison methods and a hash implementation.

weak = None

True if this is a weak tag

tag = None

the opaque tag

classmethod from_str(source)

Creates an entity-tag from a source string.

5.4.1. Parsing Parameter Values

In most cases parameter values will be parsed directly by the class methods provided in the parameter types themselves. For completeness a parameter parser is exposed to enable you to parse these values from more complex strings.

class pyslet.http.params.ParameterParser(source, ignore_sp=True)

Bases: pyslet.http.grammar.WordParser

An extended parser for parameter values

This parser defines attributes for dealing with English date names that are useful beyond the basic parsing functions to allow the formatting of date information in English regardless of the locale.

parse_http_version()

Parses an HTTPVersion instance

Returns None if no version was found.

wkday = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']

A list of English day-of-week abbreviations: wkday[0] == “Mon”, etc.

weekday = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']

A list of English day-of-week full names: weekday[0] == “Monday”

month = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

A list of English month names: month[0] == “Jan”, etc.

require_fulldate()

Parses a FullDate instance.

Raises BadSyntax if none is found.

There are three supported formats as described in the specification:

"Sun, 06 Nov 1994 08:49:37 GMT"
"Sunday, 06-Nov-94 08:49:37 GMT"
"Sun Nov  6 08:49:37 1994"

The first of these is the preferred format.

parse_delta_seconds()

Parses a delta-seconds value, see WordParser.parse_integer()

parse_charset()

Parses a charset, see WordParser.parse_tokenlower()

parse_content_coding()

Parses a content-coding, see WordParser.parse_tokenlower()

require_transfer_encoding()

Parses a TransferEncoding instance

Returns None if no transfer-encoding was found.

require_chunk()

Parses a chunk header

Returns a Chunk instance or None if no chunk was found.

require_media_type()

Parses a MediaType instance.

Raises BadSyntax if no media-type was found.

require_product_token()

Parses a ProductToken instance.

Raises BadSyntax if no product token was found.

parse_qvalue()

Parses a qvalue returning a float

Returns None if no qvalue was found.

require_language_tag()

Parses a language tag returning a LanguageTag instance. Raises BadSyntax if no language tag was found.

require_entity_tag()

Parses an entity-tag returning a EntityTag instance. Raises BadSyntax if no language tag was found.