Metadata-Version: 2.4
Name: lustr
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: MacOS :: MacOS 9
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Networking
Requires-Dist: uvloop>=0.22.1 ; extra == 'bench'
Provides-Extra: bench
Provides-Extra: socket
License-File: LICENSE
Summary: Blazingly fast implementation of asyncio event loop using PhotonLibOS under the hood with PyO3
Keywords: alibaba,asynchronous,asyncio,iouring,linux,networking,oxidized,photon,photonlibos,pyo3,unix
Home-Page: https://github.com/aekasitt/lustr
Author-email: Sitt Guruvanich <aekazitt+github@gmail.com>
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: github, https://github.com/aekasitt/lustr

# lustr

[![License: GNU GPLv3](https://img.shields.io/badge/License-GNU%20GPLv3-yellow.svg)](https://github.com/aekasitt/lustr/blob/master/LICENSE)
[![Fork](https://img.shields.io/badge/MagicStack/uvloop-beige?logo=github)](https://github.com/MagicStack/uvloop)
[![Top](https://img.shields.io/github/languages/top/aekasitt/lustr)](https://github.com/aekasitt/lustr)
[![Languages](https://img.shields.io/github/languages/count/aekasitt/lustr)](https://github.com/aekasitt/lustr)
[![Size](https://img.shields.io/github/repo-size/aekasitt/lustr)](https://github.com/aekasitt/lustr)
[![Last commit](https://img.shields.io/github/last-commit/aekasitt/lustr/master)](https://github.com/aekasitt/lustr)

[![Lustr banner](https://github.com/aekasitt/lustr/blob/master/static/lustr-banner.svg)](static/lustr-banner.svg)

lustr is a fast, drop-in replacement of the built-in asyncio
event loop.  lustr is implemented in PyO3 and uses PhotonLibOS
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:: https://raw.githubusercontent.com/MagicStack/uvloop/master/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 in a
`blog post <http://magic.io/blog/uvloop-blazing-fast-python-networking/>`_
about it.


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

uvloop requires Python 3.8 or greater and is available on PyPI.
Use pip to install it::

    $ pip install uvloop

Note that it is highly recommended to **upgrade pip before** installing
uvloop with::

    $ pip install -U pip


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

As of uvloop 0.18, the preferred way of using it is via the
``uvloop.run()`` helper function:


.. code:: python

    import uvloop

    async def main():
        # Main entry-point.
        ...

    uvloop.run(main())

``uvloop.run()`` works by simply configuring ``asyncio.run()``
to use uvloop, passing all of the arguments to it, such as ``debug``,
e.g. ``uvloop.run(main(), debug=True)``.

With Python 3.11 and earlier the following alternative
snippet can be used:

.. code:: python

    import asyncio
    import sys

    import uvloop

    async def main():
        # Main entry-point.
        ...

    if sys.version_info >= (3, 11):
        with asyncio.Runner(loop_factory=uvloop.new_event_loop) as runner:
            runner.run(main())
    else:
        uvloop.install()
        asyncio.run(main())


Building From Source
--------------------

To build uvloop, you'll need Python 3.8 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:

   .. code::

    $ python3 -m venv uvloop-dev
    $ source uvloop-dev/bin/activate

3. Install development dependencies:

   ..  code::

    $ pip install -e .[dev]

4. Build and run tests:

   .. code::

    $ make
    $ make test


License
-------

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

