README

Improved ergonomics for Python programmers wanting to use asynchronous IO.

Gruvi is an asynchronous IO library for Python. It focuses on the following desirable properties:

  • Simple. Async IO code should look just like normal code, with simple, sequential control flow and regular functions.
  • Efficient. An IO library should have a very low memory and CPU overhead, so that it can scale to small systems or to many concurrent connections.
  • Powerful. Common protocols like SSL/TLS and HTTP should be part of every IO library.

Gruvi uses libuv (via pyuv) as the underlying high-performance event-based I/O layer, and coroutines based on fibers to create a traditional sequential programming model on top of the libuv completion/callback model.

Gruvi is similar in concept existing async IO frameworks like asyncio, gevent, and eventlet. For a comparison, see Rationale.

Features

Gruvi has the following features:

  • Excellent platform support (mostly thanks to libuv). Linux, Mac OSX and Windows are all first-class citizens.
  • PEP-3156 compatible transport/protocol interface.
  • A traditional, sequential programming model based on green threads, where there is no distinction between asynchronous and normal functions.
  • Great SSL/TLS support, also on Windows. The asynchronous SSL support in the Python standard library came from Gruvi before it was included into the stdlib.
  • Small core and focus on low memory usage and fast performance. This makes Gruvi very suitable for mobile applications and embedded web servers.
  • A full suite of synchronization primitives including locks, conditions and queues.
  • Thread and fiber pools with a concurrent.futures interface.
  • Batteries includes: built-in client/server support for HTTP, JSON-RPC and D-BUS.
  • Support for Python 2.7.x and 3.3+.

Example

An simple echo server, using a StreamServer:

import gruvi

def echo_handler(stream, transport, protocol):
    while True:
        buf = stream.read1()
        if not buf:
            break
        stream.write(buf)

server = gruvi.StreamServer(echo_handler)
server.listen(('localhost', 7777))
server.run()

Requirements

You need Python 2.7 or 3.3+.

The following operating systems are currently supported:

  • Linux (might work on other Posix OSs)
  • macOS (not currently tested via CI)
  • Windows (not currently tested via CI)

Installation

Development install in a virtualenv:

$ git clone https://github.com/geertj/gruvi
$ cd gruvi
$ pip install -r requirements.txt
$ python setup.py build
$ python setup.py install

To run the test suite:

$ python runtests.py unit

For other installation options, see the Installation section in the manual.

Documentation

The documentation is available on readthedocs.

License

Gruvi is free software, provided under the MIT license.

Contact

Feel free to contact the author at geertj@gmail.com. You can also submit tickets or suggestions for improvements on Github.