circuits.http is a asynchronous framework for building web and HTTP related applications such as HTTP servers, clients, proxies and caches. It is based on two libraries which allows very powerful and flexible API design:

• circuits which provides the asynchronous event system as well as socket handling
• httoop as interface for handling of HTTP messages

The design of circuits.http is developped to build web applications in the REST architectural style.

• Standalone server
• WSGI server
• Ressource oriented design with routing via
  • Domains / Hosts
  • Paths with wildcard and regex support
  • HTTP method
• HTTPS connections
• Authentication via
  • HTTP Basic
  • HTTP Digest
  • HTTPS client/peer certificate
  • SAML 2.0 service provider
• Authorization to different Ressources via realm
• Content-Negotiation via Accept, Accept-Language
• MIME media type decoding of request payload
  • application/x-www-form-urlencoded
  • multipart/form-data
  • application/json
  • application/xml (requires defusedxml)
  • support for custom extensibility
• validation of the request payload and error handling via HTTP 422 Unprocessable Entity
• encoding of the response payload for the following MIME media types
  • application/json
  • application/xml (requires defusedxml)
  • text/plain
  • text/html (via genshi)
• HTTP redirections via 3XX status codes
• HTTP Error handling via 4XX and 5XX status codes
• Internationalization support via gettext using HTTP Accept-Language and Content-Language
• HTTP Range requests
• HTTP Caching via Cache-Control, Expires, E-Tag, Last-Modified, Pragma and Vary
• HTTP conditional requests via If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since and If-Range
• HTTP Security mechanisms
  • Content-Security-Policy
  • Strict-Transport-Security
  • X-Frame-Options
  • X-XSS-Protection
  • X-Content-Type-Options
  • X-Permitted-Cross-Domain-Policies
• Websocket protocol connections
• HTTP Expect 101 Continue per resource/request handling
• HTTP CONNECT method
• STARTTLS / Upgrading to TLS encrypted connections
• Request logging with configurable format
• Session handling via e.g. Cookies
• HTTP content encoding / compression via gzip, deflate
• HTTP chunked transfer encoding
• HTTP Trailers

• Following redirections
• Sessions via Cookies with ability to define own Cookie-Policies

• HTTP/2
• support for Python 3.5 and greater
• Forwarded HTTP Extension RFC 7239
• Prefer Header for HTTP RFC 7240
• API for Web Linking (RFC 5988)
• API for Cross-Origin Resource Sharing
• API for Content-Disposition (RFC 6266)
• PoC for a HTTP Proxy implementation
• PoC for a HTTP Cache implementation
• automatic progress report via HTTP 202 Accepted
• SAML Identity Provider
• oAuth
• HTTP Age
• HTTP Warning
• Public-Key-Pins

A simple HTTP server example with one resource which returns a plaintext document with the content "Hello World!" can be started with the following code:

Start a example server:

python examples/server/hello_world.py --bind http://0.0.0.0:8090/ --no-daemon

Request the resource either with firefox or with curl.

curl -i 'http://localhost:8090/'
firefox 'http://localhost:8090/'

from circuits.http.server.__main__ import HTTPServer
from circuits.http.server.resource import Resource, method, Domain


class HelloWorld(Resource):

	path = '/'

	@method
	def GET(self, client):
		return 'Hello World!'
	GET.codec('text/plain')


class Server(HTTPServer):

	logformat = '%(h)s %(l)s %(u)s %(t)s %(s)s "%(r)s" "%(H)s" %(b)s "%(f)s" "%(a)s"'

	def add_components(self):
		super(Server, self).add_components()
		root = Domain('localhost')
		root += HelloWorld(channel='hello-world')
		self.domains += root


Server.main()

More examples:

• Server examples
• Client examples
• A complete website using many features