uvloop Documentation

Technical Documentation: MagicStack/uvloop

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Index (`docs/index.rst`) Copy Section

.. image:: https://img.shields.io/github/actions/workflow/status/MagicStack/uvloop/tests.yml?branch=master
:target: https://github.com/MagicStack/uvloop/actions/workflows/tests.yml?query=branch%3Amaster

.. image:: https://img.shields.io/pypi/status/uvloop.svg?maxAge=2592000?style=plastic
:target: https://pypi.python.org/pypi/uvloop

.. image:: https://img.shields.io/github/stars/magicstack/uvloop.svg?style=social&label=GitHub
:target: https://github.com/MagicStack/uvloop

uvloop

uvloop is a fast, drop-in replacement of the built-in asyncio event loop.
uvloop is released under the MIT license.

uvloop and asyncio, combined with the power of async/await in Python 3.7,
makes it easier than ever to write high-performance networking code in Python.

uvloop makes asyncio fast. In fact, it is at least 2x faster than nodejs,
gevent, as well as any other Python asynchronous framework. The performance of
uvloop-based asyncio is close to that of Go programs.

You can read more about uvloop in this
blog post <http://magic.io/blog/uvloop-blazing-fast-python-networking/>_.

Architecture Copy Chapter

The asyncio module, introduced by PEP 3156, is a collection of network
transports, protocols, and streams abstractions, with a pluggable event loop.
The event loop is the heart of asyncio. It provides APIs for:

• scheduling calls,
• transmitting data over the network,
• performing DNS queries,
• handling OS signals,
• convenient abstractions to create servers and connections,
• working with subprocesses asynchronously.

uvloop implements the :class:asyncio.AbstractEventLoop interface which
means that it provides a drop-in replacement of the asyncio event loop.

uvloop is written in Cython and is built on top of libuv.

libuv is a high performance, multiplatform asynchronous I/O library used by
nodejs. Because of how wide-spread and popular nodejs is, libuv is fast and
stable.

uvloop implements all asyncio event loop APIs. High-level Python objects
wrap low-level libuv structs and functions. Inheritance is used to keep the
code DRY and ensure that any manual memory management is in sync with libuv
primitives' lifespans.

Contents Copy Chapter

.. toctree::
:maxdepth: 1

user/index
dev/index

Api Index (`docs/api/index.rst`) Copy Section

API

If you are looking for information on a specific function, class or method,
this part of the documentation is for you.

uvloop Copy Chapter

.. autoclass:: uvloop.EventLoopPolicy
:members:

.. autofunction:: uvloop.new_event_loop

.. autoclass:: uvloop.Loop
:members:
:undoc-members:
:inherited-members:

Dev Index (`docs/dev/index.rst`) Copy Section

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 Copy Chapter

.. code-block:: console

$ git clone --recursive [email protected]:MagicStack/uvloop.git

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

Build Copy Chapter

To build uvloop, you'll need Cython and Python 3.9 or greater.

.. 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 Copy Chapter

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 Copy Chapter

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

User Index (`docs/user/index.rst`) Copy Section

User Guide

This section of the documentation provides information about how to use
uvloop.

Installation Copy Chapter

uvloop is available from PyPI. It requires Python 3.9 or greater.

Use pip to install it.

.. code-block:: console

$ pip install uvloop

Using uvloop Copy Chapter

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

.. code-block:: python

import asyncio
import uvloop
asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())

Alternatively, you can create an instance of the loop manually, using:

.. code-block:: python

import asyncio
import uvloop
loop = uvloop.new_event_loop()
asyncio.set_event_loop(loop)

--- METRICS ---

• Files Extracted: 4
• Estimated Token Budget: ~1573 tokens
• Canonical Reference: https://codewiki.google/github.com/MagicStack/uvloop