PyXWF.AcceptHeaders – Dealing with HTTP Accept headers

class PyXWF.AcceptHeaders.Preference(value, q, parameters={})

Represent a preference declaration according to RFC 2616, as used in the HTTP Accept-* headers. There exist specialized subclasses for each type of supported Accept header:

AcceptPreference(value, q[, parameters])	Subclass of Preference for dealing with Accept header values.
CharsetPreference(value, q[, parameters])	Subclass of Preference for dealing with Accept-Charset header
LanguagePreference(value, q[, parameters])	Subclass of Preference for dealing with Accept-Language

Note

It is recommended that you create instances of the above classes using the respective implementation of from_header_section(). Do not create instances of this class—they’re not particularily useful.

They only differ in the way they implement the parsing method from_header_section().

Preference instances order according to an internal key which is gives a stable ordering and is hashable.

classmethod from_header_section(value, drop_parameters=False)

This method is overriden in the subclasses with custom behaviour to correctly interpret the value string.

drop_parameters indicates whether additional parameters will be dropped. These are normally passed to the parameters keyword argument of the constructor. The meaning of “parameters” is specific to the subclass.

• AcceptPreference: MIME type parameters as per RFC
• CharsetPreference: None
• LanguagePreference: in en-gb, “gb” is a parameter value

match(other_pref, allow_wildcard=True)

Try to match other_pref against this match and return a tuple reflecting the quality of the match: (wildcard_penalty, keys_used, q).

wildcard_penalty is a non-positive integer, which is equal to precedence if a wildcard match was successfully done, zero otherwise (i.e. also zero if no wildcard match was neccessary).

keys_used is the number of keys from parameters which compared equal. This is always less or equal to len(parameters).

q is the value of q of this instance or zero if the match failed.

class PyXWF.AcceptHeaders.PreferenceList(preference_class, **kwargs)

Hold a list of Preference subclass instances, where the exact subclass is specified by preference_class.

Objects of this class are iterable and respond to len(), but cannot be accessed element-wise, as that would not make any sense.

Warning

If you’re dealing with Accept-Charset headers, please do not overlook the method inject_rfc_values().

append_header(header, drop_parameters=False)

Create Preference objects from the elements in the full HTTP header value header and add them to the list. drop_parameters is passed to the respective parser method.

best_match(own_preferences, match_wildcard=True)

Return the preference to use if you can deliver all preferences in own_preferences to give the user agent the best possible quality

get_candidates(own_preferences, match_wildcard=True, include_non_matching=False, take_everything_on_empty=True)

Return a ordered list of tuples (q, pref), with q being the original quality value of the match and pref Preference object.

Takes an iterable of Preference instances own_preferences which indicate which preferences the application has (i.e. what to watch out for).

This goes through the whole process specified in RFC 2616 and is fully tested to work. The process can be tweaked a little off-spec for certain special cases:

• If match_wildcard is set to false, no wildcard matches are allowed.
• If include_non_matching is set to true, all elements from this list which did not match the own_preferences are returned too, but ordered in front of others (i.e. with lower relative preference).
• If take_everything_on_empty is set to False, an empty list is returned if no elements are in this list instead of returning the whole list of own_preferences converted into the return format specified above.

Note

The returned list is sorted for ascending match accuracies according to the RFC, not for q values. This implies that the last element of the list is the one you should pick if you can only serve the preferences given in own_preferences to comply with RFC 2616, see best_match().

get_quality(preference, match_wildcard=True)

Return the relative quality value for a given Preference preference if you were about to return it.

This goes through the whole matching process described in get_candidates(), with own_preferences set to [preference] and returns the q value of the best match.

Preference subclasses for each header type

class PyXWF.AcceptHeaders.AcceptPreference(value, q, parameters={})

Subclass of Preference for dealing with Accept header values.

class PyXWF.AcceptHeaders.CharsetPreference(value, q, parameters={})

Subclass of Preference for dealing with Accept-Charset header values.

class PyXWF.AcceptHeaders.LanguagePreference(value, q, parameters={})

Subclass of Preference for dealing with Accept-Language header values.

PreferenceList subclasses for each header type

class PyXWF.AcceptHeaders.AcceptPreferenceList(**kwargs)

Subclass of PreferenceList for HTTP Accept headers.

class PyXWF.AcceptHeaders.CharsetPreferenceList(**kwargs)

Subclass of PreferenceList for HTTP Accept-Charset headers.

inject_rfc_values()

This method must be called after all header values have been parsed with append_header() to achieve full compliance with the RFC.

This inserts a * preference if no values are present and a iso-8859-1;q=1.0 preference if no * preference and no iso-8859-1` is present.

class PyXWF.AcceptHeaders.LanguagePreferenceList(**kwargs)

Subclass of PreferenceList for HTTP Accept-Language headers.