API Reference¶
ietfparse.algorithms¶
Implementations of algorithms from various specifications.
select_content_type()
: select the best match between a HTTPAccept
header and a list of availableContent-Type
s
This module implements some of the more interesting algorithms described in IETF RFCs.
- ietfparse.algorithms.select_content_type(requested, available)[source]¶
Selects the best content type.
- Parameters:
requested – a sequence of
ContentType
instancesavailable – a sequence of
ContentType
instances that the server is capable of producing
- Returns:
the selected content type (from
available
) and the pattern that it matched (fromrequested
)- Return type:
tuple
ofContentType
instances- Raises:
NoMatch
when a suitable match was not found
This function implements the Proactive Content Negotiation algorithm as described in sections 3.4.1 and 5.3 of RFC 7231. The input is the Accept header as parsed by
parse_http_accept_header()
and a list of parsedContentType
instances. Theavailable
sequence should be a sequence of content types that the server is capable of producing. The selected value should ultimately be used as the Content-Type header in the generated response.
ietfparse.datastructures¶
Important data structures.
ContentType
: MIMEContent-Type
header.LinkHeader
: parsedLink
header.
This module contains data structures that were useful in implementing this library. If a data structure might be useful outside of a particular piece of functionality, it is fully fleshed out and ends up here.
- class ietfparse.datastructures.ContentType(content_type, content_subtype, parameters=None, content_suffix=None)[source]¶
A MIME
Content-Type
header.- Parameters:
Internet content types are described by the Content-Type header from RFC 2045. It was reused across many other protocol specifications, most notably HTTP (RFC 7231). This header’s syntax is described in RFC 2045#section-5.1. In its most basic form, a content type header looks like
text/html
. The primary content type istext
with a subtype ofhtml
. Content type headers can include parameters asname=value
pairs separated by colons.RFC 6839 added the ability to use a content type to identify the semantic value of a representation with a content type and also identify the document format as a content type suffix. For example,
application/vnd.github.v3+json
is used to identify documents that match version 3 of the GitHub API that are represented as JSON documents. The same entity encoded as msgpack would have the content typeapplication/vnd.github.v3+msgpack
. In this case, the content type identifies the information that is in the document and the suffix is used to identify the content format.
- class ietfparse.datastructures.LinkHeader(target, parameters=None)[source]¶
Represents a single link within a
Link
header.- target¶
The target URL of the link. This may be a relative URL so the caller may have to make the link absolute by resolving it against a base URL as described in RFC 3986#section-5.
- parameters¶
Possibly empty sequence of name and value pairs. Parameters are represented as a sequence since a single parameter may occur more than once.
The Link header is specified by RFC 5988. It is one of the methods used to represent HyperMedia links between HTTP resources.
ietfparse.errors¶
Exceptions raised from within ietfparse.
All exceptions are rooted at RootException
so
so you can catch it to implement error handling behavior associated with
this library’s functionality.
- exception ietfparse.errors.StrictHeaderParsingFailure(header_name, header_value)[source]¶
Non-standard header value detected.
This is raised when “strict” conformance is enabled for a header parsing function and a header value fails due to one of the “strict” rules.
See
ietfparse.headers.parse_forwarded()
for an example.
ietfparse.headers¶
Functions for parsing headers.
parse_accept()
: parse anAccept
valueparse_accept_charset()
: parse aAccept-Charset
valueparse_cache_control()
: parse aCache-Control
valueparse_content_type()
: parse aContent-Type
valueparse_forwarded()
: parse a RFC 7239Forwarded
valueparse_link()
: parse a RFC 5988Link
valueparse_list()
: parse a comma-separated list that is present in so many headers
- ietfparse.headers.parse_accept(header_value, strict=False)[source]¶
Parse an HTTP accept-like header.
- Parameters:
header_value – the header value to parse
strict – if
True
, then invalid content type values within header_value will raiseValueError
; otherwise, they are ignored
- Returns:
a
list
ofContentType
instances in decreasing quality order. Each instance is augmented with the associated quality as afloat
property namedquality
.- Raise:
ValueError
if strict is truthy and at least one value in header_value could not be parsed byparse_content_type()
Accept
is a class of headers that contain a list of values and an associated preference value. The ever present Accept header is a perfect example. It is a list of content types and an optional parameter namedq
that indicates the relative weight of a particular type. The most basic example is:Accept: audio/*;q=0.2, audio/basic
Which states that I prefer the
audio/basic
content type but will accept otheraudio
sub-types with an 80% mark down.
- ietfparse.headers.parse_accept_charset(header_value)[source]¶
Parse the
Accept-Charset
header into a sorted list.- Parameters:
header_value – header value to parse
- Returns:
list of character sets sorted from highest to lowest priority
The Accept-Charset header is a list of character set names with optional quality values. The quality value indicates the strength of the preference where 1.0 is a strong preference and less than 0.001 is outright rejection by the client.
Note
Character sets that are rejected by setting the quality value to less than 0.001. If a wildcard is included in the header, then it will appear BEFORE values that are rejected.
- ietfparse.headers.parse_accept_encoding(header_value)[source]¶
Parse the
Accept-Encoding
header into a sorted list.- Parameters:
header_value – header value to parse
- Returns:
list of encodings sorted from highest to lowest priority
The Accept-Encoding header is a list of encodings with optional quality values. The quality value indicates the strength of the preference where 1.0 is a strong preference and less than 0.001 is outright rejection by the client.
Note
Encodings that are rejected by setting the quality value to less than 0.001. If a wildcard is included in the header, then it will appear BEFORE values that are rejected.
- ietfparse.headers.parse_accept_language(header_value)[source]¶
Parse the
Accept-Language
header into a sorted list.- Parameters:
header_value – header value to parse
- Returns:
list of languages sorted from highest to lowest priority
The Accept-Language header is a list of languages with optional quality values. The quality value indicates the strength of the preference where 1.0 is a strong preference and less than 0.001 is outright rejection by the client.
Note
Languages that are rejected by setting the quality value to less than 0.001. If a wildcard is included in the header, then it will appear BEFORE values that are rejected.
- ietfparse.headers.parse_cache_control(header_value)[source]¶
Parse a Cache-Control header, returning a dictionary of key-value pairs.
Any of the
Cache-Control
parameters that do not have directives, such aspublic
orno-cache
will be returned with a value ofTrue
if they are set in the header.
- ietfparse.headers.parse_content_type(content_type, normalize_parameter_values=True)[source]¶
Parse a content type like header.
- Parameters:
- Return type:
- Returns:
a
ContentType
instance- Raises:
ValueError
if the content type cannot be reasonably parsed (e.g.,Content-Type: *
)
- ietfparse.headers.parse_forwarded(header_value, only_standard_parameters=False)[source]¶
Parse RFC7239 Forwarded header.
- Parameters:
header_value – value to parse
only_standard_parameters – if this keyword is specified and given a truthy value, then a non-standard parameter name will result in
StrictHeaderParsingFailure
- Returns:
- Raises:
ietfparse.errors.StrictHeaderParsingFailure
is raised if only_standard_parameters is enabled and a non-standard parameter name is encountered
This function parses a RFC 7239 HTTP header into a
list
ofdict
instances with each instance containing the param values. The list is ordered as received from left to right and the parameter names are folded to lower case strings.
- ietfparse.headers.parse_link(header_value, strict=True)[source]¶
Parse a HTTP Link header.
- Parameters:
- Returns:
a sequence of
LinkHeader
instances- Raises:
ietfparse.errors.MalformedLinkValue – if the specified header_value cannot be parsed