3. Package Contents/API

The httpy package defines classes to represent HTTP Request and Response messages. It also defines interfaces specifying how to build responders and couplers, specimens of which are to be found in the responders and couplers subpackages. Finally, the mode singleton provides an object-oriented API for the HTTPY_MODE environment variable, and the utils subpackage collects some other possibly useful tools.

class Request( IRequest): Constructs a new Request object. IRequest is a (probably implicit) provider of the IRequest interface. This provision is validated, and the desired API is transferred from the IRequest provider to the new object instance.
Your responder's respond method will be given instances of this class, so you will be using it constantly on that basis. However, you would probably only need to instantiate it directly if you were writing a new coupler.

class Response( [code] [, body] [, headers])

Constructs a new Response object. If given, code must be an integer; the default is 200 (see the HTTP spec for other values that will be meaningful to most HTTP clients). body may be a string or an iterator over strings. headers may be a dictionary or a list of 2-tuples.

body is second rather than headers because one more often wants to specify a body without headers than vice versa. Also note that Content-Type: defaults to text/html for responses where code is between 200 and 299, inclusive, but to text/plain for non-2xx responses.

This class is likewise central to httpy programming: its instances are what your responders return or raise. These will be captured, validated, flattened, and sent out to the wire by whatever coupler is in use.