Degu
====

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.


.. _`LGPLv3+`: https://www.gnu.org/licenses/lgpl-3.0.html
.. _`Python 3.4`: https://docs.python.org/3.4/
.. _`Python 3.5`: https://docs.python.org/3.5/

.. _`Documentation`: http://docs.novacut.com/degu/index.html
.. _`Report a bug`: https://bugs.launchpad.net/degu
.. _`Browse the source`: http://bazaar.launchpad.net/~dmedia/degu/trunk/files
.. _`Launchpad project`: https://launchpad.net/degu

.. _`Novacut`: https://launchpad.net/novacut
.. _`Ubuntu`: http://www.ubuntu.com/
.. _`Novacut Stable Releases PPA`: https://launchpad.net/~novacut/+archive/ubuntu/stable
.. _`Novacut Daily Builds PPA`: https://launchpad.net/~novacut/+archive/ubuntu/daily
.. _`#novacut`: https://webchat.freenode.net/?channels=novacut