1.1 Overview

httpy's job is to get HTTP requests off the wire into your Python program, and to get HTTP responses from your program back onto the wire. Within this narrow ambit, we include batteries: you shouldn't have to resort to another library for anything between the wire and your app. At the same time, we aim for a sane and satisfying API. Beyond the basic modeling of HTTP Request and Response messages, httpy is organized around just two types of Python objects:

responders: A responder is a module or class with a callable, respond(), that takes a single argument, an httpy.Request object. This callable is expected to raise (!) an httpy.Response object.
couplers: A coupler puts a responder onto the network.

httpy's Request and Response objects are wooden representations of their HTTP counterparts. Likewise, couplers are rather pedestrian: that's where the socket and gateway programming happens. httpy's chief innovation is in overloading Python's raise statement to represent the end of an HTTP transaction. This turns out to be a natural fit: HTTP transactions usually see requests pass through multiple layers on their way to an origin server - routers, gateways, proxies, caches - before ending abruptly at any of a number of places on this stack, with a response zipping back up the stack to the client. httpy turns the Python interpreter's call stack into an extension of the HTTP stack.