.. aiozmq documentation master file, created by
   sphinx-quickstart on Mon Mar 17 15:12:47 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

aiozmq
====================================

ZeroMQ integration with asyncio (:pep:`3156`).

.. _GitHub: https://github.com/aio-libs/aiozmq


Features
--------

- Implements :func:`~aiozmq.create_zmq_connection` coroutine for
  making 0MQ connections.
- Provides :class:`~aiozmq.ZmqTransport` and :class:`~aiozmq.ZmqProtocol`
- Provides RPC :ref:`aiozmq-rpc-rpc`, :ref:`aiozmq-rpc-pushpull` and
  :ref:`aiozmq-rpc-pubsub` patterns for *remote calls*.

.. note::

   The library works on Linux, MacOS X and Windows.

   But Windows is a second-class citizen in :term:`ZeroMQ` world, sorry.

   Thus *aiozmq* has *limited* support for Windows also.

   Limitations are:

   * You obviously cannot use *ipc://name* schema for :term:`endpoint`
   * aiozmq`s loop :class:`aiozmq.ZmqEventLoop` is built on top of ``select``
     system call, so it's not fast comparing to
     :class:`asyncio.ProactorEventLoop` and it doesn't support
     :ref:`subprocesses <asyncio-subprocess>`.

Library Installation
--------------------

The :ref:`core <aiozmq-core>` requires only :term:`pyzmq` and can
be installed (with pyzmq as dependency) by executing::

   pip3 install aiozmq

Also probably you want to use :mod:`aiozmq.rpc`.


.. _aiozmq-install-msgpack:

RPC module is **optional** and requires :term:`msgpack`. You can
install *msgpack* by executing::

  pip3 install msgpack

.. note::

   *aiozmq* can be executed by *Python 3* only. The most Linux
   distributions uses *pip3* for installing *Python 3 libraries*.
   But your system may be using *Python 3* by default than try
   just *pip* instead of *pip3*. The same may be true for *virtualenv*,
   *travis continuous integration system* etc.

Source code
-----------

The project is hosted on GitHub_

Please feel free to file an issue on `bug tracker
<https://github.com/aio-libs/aiozmq/issues>`_ if you have found a bug
or have some suggestion for library improvement.

The library uses Github Actions for
Continious Integration.


Dependencies
------------

- Python 3.6+
- :term:`ZeroMQ` 3.2+
- :term:`pyzmq` 13.1+ (did not test with earlier versions)
- aiozmq.rpc requires :term:`msgpack`

Authors and License
-------------------

The ``aiozmq`` package is initially written by Nikolay Kim, later
maintained by Andrew Svetlov, and now by Jelle Zijlstra.
It's BSD licensed and freely available.
Feel free to improve this package and send a pull request to GitHub_.

Getting Started
---------------

Low-level request-reply example::

    import asyncio
    import aiozmq
    import zmq

    async def go():
        router = await aiozmq.create_zmq_stream(
            zmq.ROUTER,
            bind='tcp://127.0.0.1:*')

        addr = list(router.transport.bindings())[0]
        dealer = await aiozmq.create_zmq_stream(
            zmq.DEALER,
            connect=addr)

        for i in range(10):
            msg = (b'data', b'ask', str(i).encode('utf-8'))
            dealer.write(msg)
            data = await router.read()
            router.write(data)
            answer = await dealer.read()
            print(answer)
        dealer.close()
        router.close()

    asyncio.run(go())


Example of RPC usage::

    import asyncio
    import aiozmq.rpc

    class ServerHandler(aiozmq.rpc.AttrHandler):
        @aiozmq.rpc.method
        def remote_func(self, a:int, b:int) -> int:
            return a + b

    async def go():
        server = await aiozmq.rpc.serve_rpc(
            ServerHandler(), bind='tcp://127.0.0.1:5555')
        client = await aiozmq.rpc.connect_rpc(
            connect='tcp://127.0.0.1:5555')

        ret = await client.call.remote_func(1, 2)
        assert 3 == ret

        server.close()
        client.close()

    asyncio.run(go())

.. note:: To execute the last example you need to :ref:`install
   msgpack<aiozmq-install-msgpack>` first.


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. toctree::

   stream
   rpc
   core
   examples
   glossary
