README.rst 2.08 KB
Newer Older
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
.. image:: https://travis-ci.org/MagicStack/uvloop.svg?branch=master
    :target: https://travis-ci.org/MagicStack/uvloop

.. image:: https://img.shields.io/pypi/v/uvloop.svg
    :target: https://pypi.python.org/pypi/uvloop


uvloop is a fast, drop-in replacement of the built-in asyncio
event loop.  uvloop is implemented in Cython and uses libuv
under the hood.

The project documentation can be found
`here <http://uvloop.readthedocs.org/>`_.  Please also check out the
`wiki <https://github.com/MagicStack/uvloop/wiki>`_.


Performance
-----------

uvloop makes asyncio 2-4x faster.

.. image:: performance.png
    :target: http://magic.io/blog/uvloop-blazing-fast-python-networking/

The above chart shows the performance of an echo server with different
message sizes.  The *sockets* benchmark uses ``loop.sock_recv()`` and
``loop.sock_sendall()`` methods; the *streams* benchmark uses asyncio
high-level streams, created by the ``asyncio.start_server()`` function;
and the *protocol* benchmark uses ``loop.create_server()`` with a simple
echo protocol.  Read more about uvloop
`performance <http://magic.io/blog/uvloop-blazing-fast-python-networking/>`_.


Installation
------------

37
uvloop requires Python 3.5 or greater and is available on PyPI.
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
Use pip to install it::

    $ pip install uvloop


Using uvloop
------------

To make asyncio use uvloop, you can install the uvloop event
loop policy:

.. code:: python

    import asyncio
    import uvloop
53

54 55 56
    asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())


57 58 59 60 61 62 63 64 65 66 67 68 69
Building From Source
--------------------

To build uvloop, you'll need Python 3.5 or greater:

1. Clone the repository:

   .. code::

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

2. Create a virtual environment and activate it, for example:
70

71
   .. code::
72

73 74
    $ python3.7 -m venv uvloop-dev
    $ source uvloop-dev/bin/activate
75

76
3. Install development dependencies:
77

78
   ..  code::
79

80
    $ pip install -r requirements.dev.txt
81

82
4. Build and run tests:
83

84
   .. code::
85

86
    $ make && make test
87 88 89 90 91 92


License
-------

uvloop is dual-licensed under MIT and Apache 2.0 licenses.