This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description
Negotiator
==========

Proper Content Negotiation for Python

Introduction
------------

Negotiator offers a framework for making content negotiation decisions based on the HTTP accept headers.

NOTE it currently only formally supports Accept and Accept-Language, but it is a short haul to support for Accept-Charset and Accept-Encoding (TODO)


Basic Usage
-----------

Import all the objects from the negotiator module

>>> from negotiator import ContentNegotiator, AcceptParameters, ContentType, Language

Specify the default parameters. These are the parameters which will be used in place of any HTTP Accept headers which are not present in the negotiation request. For example, if the Accept-Language header is not passed to the negotiator it will assume that the client request is for "en"

>>> default_params = AcceptParameters(ContentType("text/html"), Language("en"))

Specify the list of acceptable formats that the server supports

>>> acceptable = [AcceptParameters(ContentType("text/html"), Language("en"))]
>>> acceptable.append(AcceptParameters(ContentType("text/json"), Language("en")))

Create an instance of the negotiator, ready to accept negotiation requests

>>> cn = ContentNegotiator(default_params, acceptable)

A simple negotiate on the HTTP Accept header "text/json;q=1.0, text/html;q=0.9", asking for json, and if not json then html

>>> acceptable = cn.negotiate(accept="text/json;q=1.0, text/html;q=0.9")

The negotiator indicates that the best match the server can give to the client's request is text/json in english

>>> acceptable
AcceptParameters:: Content Type: text/json;Language: en;


Advanced Usage
--------------

Import all the objects from the negotiator module

>>> from negotiator import ContentNegotiator, AcceptParameters, ContentType, Language

Specify the default parameters. These are the parameters which will be used in place of any HTTP Accept headers which are not present in the negotiation request. For example, if the Accept-Language header is not passed to the negotiator it will assume that the client request is for "en"

>>> default_params = AcceptParameters(ContentType("text/html"), Language("en"))

Specify the list of acceptable formats that the server supports. For this advanced example we specify html, json and pdf in a variety of languages

>>> acceptable = [AcceptParameters(ContentType("text/html"), Language("en"))]
>>> acceptable.append(AcceptParameters(ContentType("text/html"), Language("fr")))
>>> acceptable.append(AcceptParameters(ContentType("text/html"), Language("de")))
>>> acceptable.append(AcceptParameters(ContentType("text/json"), Language("en")))
>>> acceptable.append(AcceptParameters(ContentType("text/json"), Language("cz")))
>>> acceptable.append(AcceptParameters(ContentType("application/pdf"), Language("de")))

specify the weighting that the negotiator should apply to the different Accept headers. A higher weighting towards content type will prefer content type variations over language variations (e.g. if there are two formats which are equally acceptable to the client, in different languages, a content_type weight higher than a language weight will return the parameters according to the server's preferred content type.

>>> weights = {"content_type" : 1.0, "language" : 0.5}

Create an instance of the negotiator, ready to accept negotiation requests

>>> cn = ContentNegotiator(default_params, acceptable, weights)

set up some more complex accept headers (you can try modifying the order of the elements without q values, and the q values themselves, to see different results).

>>> accept = "text/html, text/json;q=1.0, application/pdf;q=0.5"
>>> accept_language = "en;q=0.5, de, cz, fr"

negotiate over both headers, looking for an optimal solution to the client request

>>> acceptable = cn.negotiate(accept, accept_language)

The negotiator indicates the best fit to the client request is text/html in German

>>> acceptable
AcceptParameters:: Content Type: text/html;Language: de;


Preference Ordering Rules
-------------------------

The Negotiator organises the preferences in each accept header into a sequence,
from highest q value to lowest, grouping together equal q values.

For example, the HTTP Accept header:

"text/html, text/json;q=1.0, application/pdf;q=0.5"

Would result in the following preference sequence (as a python dictionary):

{
1.0 : ["text/json", "text/html"],
0.5 : ["application/pdf"]
}

While the HTTP Accept-Language header:

"en;q=0.5, de, cz, fr"

Would result in the following preference sequence (as a python dictionary):

{
1.0 : ["de"],
0.8 : ["cz"],
0.6 : ["fr"],
0.5 : ["en"]
}

(In reality, the q values for de, cz and fr would be evenly spaced between 1.0 and 0.5, using floating point numbers as the keys)


Combined Preference Ordering Rules
----------------------------------

The negotiator will compute all the possible allowed combinations and their weighted overall q values.

Given that the server supports the following combinations (from the code example above):

text/html, en
text/html, fr
text/html, de
text/json, en
text/json, cz
application/pdf, de

And given the weights:

w = {"content_type" : 1.0, "language" : 0.5}

We can calculate the combined q value of each allowed (by both server and client) option, using the equation:

overall_q = w["content_type"] * content_type_q + w["language"] * language_q

So, for the above options and q values from the previous section, we can generate the preference list (as a python dictionary):

{
1.5 : ["text/html, de"],
1.4 : ["text/json, cz"],
1.3 : ["text/html, fr"],
1.25 : ["text/html, en", "text/json, en"]
1.0 : ["application/pdf, de"]
}

It is clear, then, why the negotiator in the Advanced Usage section selected "text/html, de" as its preferred format.
Release History

Release History

1.0.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
negotiator-1.0.0.tar.gz (12.0 kB) Copy SHA256 Checksum SHA256 Source Mar 14, 2012

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting