pants.contrib.http

Server

class pants.contrib.http.HTTPServer(request_handler, max_request=10485760, keep_alive=True, ssl_options=None, cookie_secret=None, xheaders=False)

An HTTP server, extending the default Server class.

This class automatically uses the HTTPConnection connection class. Rather than through specifying a connection class, its behavior is customized by providing a request handler function that is called whenever a valid request is received.

A server’s behavior is defined almost entirely by its request handler, and will not send any response by itself unless the received HTTP request is not valid or larger than the specified limit (which defaults to 10 MiB).

Argument	Default	Description
request_handler		A callable that accepts a single argument. That argument is an instance of the HTTPRequest class representing the current request.
max_request	10 MiB	Optional. The maximum allowed length, in bytes, of an HTTP request body. This should be kept small, as the entire request body will be held in memory.
keep_alive	True	Optional. Whether or not multiple requests are allowed over a single connection.
ssl_options	None	Optional. SSL is not currently implemented in Pants, and this will not work. A dictionary of options for establishing SSL connections. If this is set, the server will serve requests via HTTPS. The keys and values provided by the dictionary should mimic the arguments taken by ssl.wrap_socket().
cookie_secret	None	Optional. A string to use when signing secure cookies.
xheaders	False	Optional. Whether or not to use X-Forwarded-For and X-Forwared-Proto headers.

class pants.contrib.http.HTTPConnection(*args)

Instances of this class represent connections received by an HTTPServer, and perform all the actual logic of receiving and responding to an HTTP request.

In order, this class is in charge of: reading HTTP request lines, reading the associated headers, reading any request body, and executing the appropriate request handler if the request is valid.

You will almost never access this class directly.

class pants.contrib.http.HTTPRequest(connection, method, uri, http_version, headers=None, protocol='http')

Instances of this class represent single HTTP requests that an HTTPServer has received. Such instances contain all the information needed to respond to the request, as well as the functions used to actually send a response.

This class should, generally, not be used directly. Instead, allow the HTTPServer to create instances for you.

Argument	Description
connection	The instance of HTTPConnection that received this request.
method	The HTTP method used to send this request. This will almost always be one of: GET, HEAD, or POST.
uri	The path part of the URI requested.
http_version	The HTTP protocol version used for this request. This will almost always be one of: HTTP/1.0 or HTTP/1.1.
headers	Optional. A dictionary of HTTP headers received with this request.
protocol	Optional. Either the string http or https, depending on the security of the connection this request was received upon.

Client

class pants.contrib.http.HTTPClient(response_handler=None, max_redirects=5, keep_alive=True, unicode=True)

An HTTP client, capable of communicating with most, if not all, servers using an incomplete implementation of HTTP protocol version 1.1.

The behavior of an instance of HTTPClient is determined by that instance’s on_response() function. That function may be changed by subclassing HTTPClient, assigning it directly, or supplying a suitable callable as the first argument when creating an instance of HTTPClient.

Argument	Default	Description
response_handler	None	Optional. A callable that will handle any received responses.
max_redirects	5	Optional. The number of times to follow a redirect issued by the server.
keep_alive	True	Optional. Whether or not a single connection will be reused for multiple requests.
unicode	True	Optional. Whether or not to attempt to convert the response body to unicode using the provided Content-Type header’s encoding information.

class pants.contrib.http.ClientHelper(parent)

An instance of this class is returned by calls to HTTPClient.get() and HTTPClient.post() to allow for a bit of decorator magic.

For further information, please see the HTTPClient documentation.

class pants.contrib.http.HTTPResponse(client, request, http_version, status, status_text, headers)

Instances of this class represent singular HTTP responses that an instance of HTTPClient has received. Such instances contain all the information needed to act upon a response.

This class should, generally, not be used directly. Instead, allow the HTTPClient to create instances for you.

Argument	Description
client	The instance of HTTPClient that received this response.
request	The request list, containing all the information passed to the call that generated the request responsible for this response.
http_version	The HTTP protocol version used in this response. This will almost always be one of: HTTP/1.0 or HTTP/1.1.
status	The HTTP status code received with this response.
status_text	The human readable status message that goes with the received status code.
headers	A dictionary of HTTP headers received with this response.