1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
Developers Guide
================
The project is hosted on `GitHub <https://github.com/MagicStack/uvloop>`_.
and uses `GitHub Actions <https://github.com/MagicStack/uvloop/actions>`_ 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 <https://github.com/MagicStack/uvloop/issues>`_.
Get the source
--------------
.. code-block:: console
$ 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.8.
.. 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.
.. code-block:: console
$ python3 -m venv myvenv
$ source myvenv/bin/activate
Install Cython if not already present.
.. code-block:: console
$ pip install Cython
Build `uvloop` by running the ``make`` rule from the top level directory.
.. code-block:: console
$ 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.
.. code-block:: console
$ 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``:
.. code-block:: console
$ cd uvloop
$ pip install -e .
You can then run the unit tests individually from the tests directory using
``unittest``:
.. code-block:: console
$ cd uvloop/tests
$ python -m unittest test_tcp
or using ``pytest``:
.. code-block:: console
$ 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 <http://sphinx-doc.org/>`_ html content.
This step requires Sphinx to be installed. Sphinx can be installed using
pip:
.. code-block:: console
$ pip install sphinx
Once Sphinx is available you can make the documentation using:
.. code-block:: console
$ make docs
|
