degu 0.18.0

Embedded HTTP server and client library

Degu is an embedded HTTP server and client library for Python3.

It can be used to build network-transparent services, whether the other endpoint is in the cloud, on the local network, on the localhost, or even on the localhost using HTTP over AF_UNIX.

Degu is especially well suited for implementing REST APIs for device-to-device communication (Internet of Things). It’s a building block for future stuff, your vehicle into bold, uncharted territory.

Degu is licensed LGPLv3+, requires Python 3.4 or newer, and fully supports Python 3.5.

Some noteworthy features:

• Degu fully exposes HTTP chunked transfer-encoding semantics, including the optional per-chunk extension

• Degu fully exposes IPv6 address semantics, including the scopeid needed for IPv6 link-local addresses

• Degu transparently supports AF_INET, AF_INET6, and AF_UNIX, all via a single address argument used uniformly by the server and client

• Degu provides a safe and opinionated API for using TLSv1.2, with a particular focus on using client certificates to authenticate incoming TCP connections

Examples

Define a simple REST Gateway Interface (RGI) server application:

>>> def app(session, request, api):
...     if request.method != 'GET':
...         return (405, 'Method Not Allowed', {}, None)
...     if request.path != ['example']:
...         return (404, 'Not Found', {}, None)
...     return (200, 'OK', {}, b'hello, world')
...

Run the above app on a throw-away server listening on a random, unprivileged port:

>>> from degu.misc import TempServer
>>> server = TempServer(('127.0.0.1', 0), app)

Create a client for making connections to the above server:

>>> from degu.client import Client
>>> client = Client(server.address)

(The server.address attribute will include the random port assigned by the kernel.)

Create a connection and make a 'GET' request:

>>> conn = client.connect()
>>> response = conn.get('/example', {})

The return value is a Response namedtuple:

>>> response
Response(status=200, reason='OK', headers={'content-length': 12}, body=Body(<reader>, 12))

Read the response body like this:

>>> response.body.read()
b'hello, world'

Make another 'GET' request, this time for a URI that will return a 404 Not Found error:

>>> conn.get('/nope', {})
Response(status=404, reason='Not Found', headers={}, body=None)

Degu resources

• Documentation

• Report a bug

• Browse the source

• Launchpad project

Performance

The Degu server and client use a shared HTTP backend implemented in C. Degu is optimized for low-latency and high-throughput when operating at modest concurrency.

When both endpoints are running on the localhost, a Degu client+server duo is impressively quick for small request/response made sequentially through the same connection.

On an Intel i7-4900MQ CPU running Ubuntu 14.04 LTS (64-bit), Degu can achieve an average of:

• Over 76k request/response round-trips per second over AF_UNIX (less than 13.2μs per round-trip)

• Over 53k request/response round-trips per second over AF_INET6 (less than 18.9μs per round-trip)

This level of performance makes HTTP perfectly viable for Inter Process Communication (IPC), with the added bonus that you get the same REST API goodness whether the server is running locally or remotely.

A Novacut component

Degu is being developed as part of the Novacut project. Packages are available for Ubuntu in the Novacut Stable Releases PPA and the Novacut Daily Builds PPA.

If you have questions or need help getting started with Degu, please stop by the #novacut IRC channel on freenode.