Developers Guide

The project is hosted on GitHub. and uses Travis for Continuous Integration.

A goal for the uvloop project is to provide a drop in replacement for the asyncio event loop. Any deviation from the behavior of the reference asyncio event loop is considered a bug.

If you have found a bug or have an idea for an enhancement that would improve the library, use the bug tracker.

Get the source

$ git clone --recursive git@github.com:MagicStack/uvloop.git

The --recursive argument is important. It will fetch the libuv source from the libuv Github repository.

Build

To build uvloop, you’ll need Cython and Python 3.5.

Note

The best way to work on uvloop is to create a virtual env, so that you’ll have Cython and Python commands pointing to the correct tools.

$ python3 -m venv myvenv
$ cd myvenv
$ source bin/activate
$ cd ..

Install Cython if not already present.

$ pip install Cython

Build uvloop by running the make rule from the top level directory.

$ cd uvloop
$ make

Test

The easiest method to run all of the unit tests is to run the make test rule from the top level directory. This runs the standard library unittest tool which discovers all the unit tests and runs them. It actually runs them twice, once with the PYTHONASYNCIODEBUG enabled and once without.

$ cd uvloop
$ make test

Individual Tests

Individual unit tests can be run using the standard library unittest or pytest package.

The easiest approach to ensure that uvloop can be found by Python is to install the package using pip:

$ cd uvloop
$ pip install -e .

You can then run the unit tests individually from the tests directory using unittest:

$ cd uvloop/tests
$ python -m unittest test_tcp

or using pytest:

$ cd uvloop/tests
$ py.test -k test_signals_sigint_uvcode

Documentation

To rebuild the project documentation, developers should run the make docs rule from the top level directory. It performs a number of steps to create a new set of sphinx html content.

This step requires Sphinx to be installed. Sphinx can be installed using pip:

$ pip install sphinx

Once Sphinx is available you can make the documentation using:

$ make docs