## File: README.md

# PyZMQ: Python bindings for ØMQ

This package contains Python bindings for [ZeroMQ](https://zeromq.org).
ØMQ is a lightweight and fast messaging implementation.

PyZMQ should work with any reasonable version of Python (≥ 3.9), as well as PyPy.
PyZMQ supports libzmq ≥ 3.2.2 (including 4.x).

For a summary of changes to pyzmq, see our
[changelog](https://pyzmq.readthedocs.io/en/latest/changelog.html).

### ØMQ 3.x, 4.x

PyZMQ fully supports the stable (not DRAFT) 3.x and 4.x APIs of libzmq,
developed at [zeromq/libzmq](https://github.com/zeromq/libzmq).
No code to change, no flags to pass,
just build pyzmq against the latest and it should work.

## Documentation

See PyZMQ's Sphinx-generated
documentation [on Read the Docs](https://pyzmq.readthedocs.io) for API
details, and some notes on Python and Cython development. If you want to
learn about using ØMQ in general, the excellent [ØMQ
Guide](http://zguide.zeromq.org/py:all) is the place to start, which has a
Python version of every example. We also have some information on our
[wiki](https://github.com/zeromq/pyzmq/wiki).

## Downloading

Unless you specifically want to develop PyZMQ, we recommend downloading
the PyZMQ source code or wheels from
[PyPI](https://pypi.io/project/pyzmq/),
or install with conda.

You can also get the latest source code from our GitHub repository, but
building from the repository will require that you install recent Cython.

## Building and installation

For more detail on building pyzmq, see [our docs](https://pyzmq.readthedocs.io/en/latest/howto/build.html).

We build wheels for macOS, Windows, and Linux, so you can get a binary on those platforms with:

```
pip install pyzmq
```

but compiling from source with `pip install pyzmq` should work in most environments.
Make sure you are using the latest pip, or it may not find the right wheels.

If the wheel doesn't work for some reason, or you want to force pyzmq to be compiled
(this is often preferable if you already have libzmq installed and configured the way you want it),
you can force installation from source with:

```
pip install --no-binary=pyzmq pyzmq
```

## Old versions

pyzmq 16 drops support Python 2.6 and 3.2.
If you need to use one of those Python versions, you can pin your pyzmq version to before 16:

```
pip install 'pyzmq<16'
```

For libzmq 2.0.x, use 'pyzmq\<2.1'

pyzmq-2.1.11 was the last version of pyzmq to support Python 2.5,
and pyzmq ≥ 2.2.0 requires Python ≥ 2.6.
pyzmq-13.0.0 introduces PyPy support via CFFI, which only supports libzmq-3.2.2 and newer.

PyZMQ releases ≤ 2.2.0 matched libzmq versioning, but this is no longer the case,
starting with PyZMQ 13.0.0 (it was the thirteenth release, so why not?).
PyZMQ ≥ 13.0 follows semantic versioning conventions accounting only for PyZMQ itself.

---

## File: docs/source/api/index.md

---
Date: '{{ today }}'
Release: '{{ release }}'
---

(api-index)=

# The PyZMQ API

```{toctree}
zmq
zmq.devices
zmq.decorators
zmq.green
zmq.eventloop.ioloop
zmq.eventloop.future
zmq.asyncio
zmq.eventloop.zmqstream
zmq.auth
zmq.auth.asyncio
zmq.auth.thread
zmq.auth.ioloop
zmq.log.handlers
zmq.ssh.tunnel
zmq.utils.jsonapi
zmq.utils.monitor
zmq.utils.z85
zmq.utils.win32
```

---

## File: docs/source/api/zmq.asyncio.md

# asyncio

## Module: {mod}`zmq.asyncio`

```{eval-rst}
.. automodule:: zmq.asyncio
```

```{currentmodule} zmq.asyncio
```

```{versionadded} 15.0
```

As of 15.0, pyzmq now supports {mod}`asyncio`, via {mod}`zmq.asyncio`.
When imported from this module, blocking methods such as
{meth}`Socket.recv_multipart`, {meth}`Socket.poll`,
and {meth}`Poller.poll` return {class}`~.asyncio.Future` s.

```python
import asyncio
import zmq
import zmq.asyncio

ctx = zmq.asyncio.Context()


async def recv_and_process():
    sock = ctx.socket(zmq.PULL)
    sock.bind(url)
    msg = await sock.recv_multipart()  # waits for msg to be ready
    reply = await async_process(msg)
    await sock.send_multipart(reply)


asyncio.run(recv_and_process())
```

## Classes

### {class}`Context`

Context class that creates Future-returning sockets. See {class}`zmq.Context` for more info.

```{eval-rst}
.. autoclass:: Context


```

### {class}`Socket`

Socket subclass that returns {class}`asyncio.Future` s from blocking methods,
for use in coroutines and async applications.

```{seealso}
{class}`zmq.Socket` for the inherited API.
```

```{eval-rst}
.. autoclass:: Socket

  .. automethod:: recv

  .. automethod:: recv_multipart

  .. automethod:: send

  .. automethod:: send_multipart

  .. automethod:: poll

```

### {class}`Poller`

Poller subclass that returns {class}`asyncio.Future` s from poll,
for use in coroutines and async applications.

```{seealso}
{class}`zmq.Poller` for the inherited API.
```

```{eval-rst}
.. autoclass:: Poller

  .. automethod:: poll
```

---

## File: docs/source/api/zmq.auth.asyncio.md

# auth.asyncio

## Module: {mod}`zmq.auth.asyncio`

```{eval-rst}
.. automodule:: zmq.auth.asyncio
```

```{currentmodule} zmq.auth.asyncio
```

## Classes

### {class}`AsyncioAuthenticator`

```{eval-rst}
.. autoclass:: AsyncioAuthenticator
  :members:
  :undoc-members:
  :inherited-members:
```

---

## File: docs/source/api/zmq.auth.ioloop.md

# auth.ioloop

## Module: :mod}\`zmq.auth.ioloop\`

```{eval-rst}
.. module:: zmq.auth.ioloop
```

This module is deprecated in pyzmq 25.
Use {mod}`zmq.auth.asyncio`.

---

## File: docs/source/api/zmq.auth.md

# auth

## Module: {mod}`zmq.auth`

```{eval-rst}
.. automodule:: zmq.auth
```

```{currentmodule} zmq.auth
```

## {class}`Authenticator`

```{eval-rst}
.. autoclass:: Authenticator
  :members:
  :undoc-members:
  :inherited-members:

```

## Functions

```{eval-rst}
.. autofunction:: create_certificates
```

```{eval-rst}
.. autofunction:: load_certificate
```

```{eval-rst}
.. autofunction:: load_certificates
```

---

## File: docs/source/api/zmq.auth.thread.md

% AUTO-GENERATED FILE -- DO NOT EDIT!

# auth.thread

## Module: {mod}`zmq.auth.thread`

```{eval-rst}
.. automodule:: zmq.auth.thread
```

```{currentmodule} zmq.auth.thread
```

## Classes

### {class}`ThreadAuthenticator`

```{eval-rst}
.. autoclass:: ThreadAuthenticator
  :members:
  :undoc-members:
  :inherited-members:
```

```{eval-rst}
.. autoclass:: AuthenticationThread
```

---

## File: docs/source/api/zmq.decorators.md

# decorators

## Module: {mod}`zmq.decorators`

```{eval-rst}
.. automodule:: zmq.decorators
```

```{currentmodule} zmq.decorators
```

## Decorators

```{eval-rst}
.. autofunction:: zmq.decorators.context
```

```{eval-rst}
.. autofunction:: zmq.decorators.socket
```

---

## File: docs/source/api/zmq.devices.md

# devices

## Functions

```{eval-rst}
.. autofunction:: zmq.device
    :noindex:
```

```{eval-rst}
.. autofunction:: zmq.proxy
    :noindex:
```

```{eval-rst}
.. autofunction:: zmq.proxy_steerable
    :noindex:
```

## Module: {mod}`zmq.devices`

```{eval-rst}
.. automodule:: zmq.devices
```

```{currentmodule} zmq.devices
```

## Base Devices

### {class}`Device`

```{eval-rst}
.. autoclass:: Device
  :members:
  :exclude-members: context_factory, run, run_device
```

### {class}`ThreadDevice`

```{eval-rst}
.. autoclass:: ThreadDevice
  :members:
```

### {class}`ProcessDevice`

```{eval-rst}
.. autoclass:: ProcessDevice
  :members:

```

## Proxy Devices

### {class}`Proxy`

```{eval-rst}
.. autoclass:: Proxy
  :members: bind_mon, connect_mon, setsockopt_mon
```

### {class}`ThreadProxy`

```{eval-rst}
.. autoclass:: ThreadProxy
  :members:
```

### {class}`ProcessProxy`

```{eval-rst}
.. autoclass:: ProcessProxy
  :members:
```

### {class}`ProxySteerable`

```{eval-rst}
.. autoclass:: ProxySteerable
  :members: bind_ctrl, connect_ctrl, setsockopt_ctrl
```

### {class}`ThreadProxySteerable`

```{eval-rst}
.. autoclass:: ThreadProxySteerable
  :members:
```

### {class}`ProcessProxySteerable`

```{eval-rst}
.. autoclass:: ProcessProxySteerable
  :members:
```

## MonitoredQueue Devices

```{eval-rst}
.. autofunction:: zmq.devices.monitored_queue
```

### {class}`MonitoredQueue`

```{eval-rst}
.. autoclass:: MonitoredQueue
  :members:
```

### {class}`ThreadMonitoredQueue`

```{eval-rst}
.. autoclass:: ThreadMonitoredQueue
  :members:
```

### {class}`ProcessMonitoredQueue`

```{eval-rst}
.. autoclass:: ProcessMonitoredQueue
  :members:
```

---

## File: docs/source/api/zmq.eventloop.future.md

% AUTO-GENERATED FILE -- DO NOT EDIT!

# eventloop.future

## Module: {mod}`zmq.eventloop.future`

```{eval-rst}
.. automodule:: zmq.eventloop.future
```

```{currentmodule} zmq.eventloop.future
```

```{versionadded} 15.0
```

As of pyzmq 15, there is a new Socket subclass that returns Futures for recv methods,
which can be found at {class}`Socket`.
You can create these sockets by instantiating a {class}`Context`
from the same module.
These sockets let you easily use zmq with tornado's coroutines.

```{seealso}
{mod}`tornado.gen`
```

```python
from tornado import gen
from zmq.eventloop.future import Context

ctx = Context()


@gen.coroutine
def recv_and_process():
    sock = ctx.socket(zmq.PULL)
    sock.bind(url)
    msg = yield sock.recv_multipart()  # waits for msg to be ready
    reply = yield async_process(msg)
    yield sock.send_multipart(reply)
```

## Classes

### {class}`Context`

Context class that creates Future-returning sockets. See {class}`zmq.Context` for more info.

```{eval-rst}
.. autoclass:: Context

```

### {class}`Socket`

Socket subclass that returns {class}`~tornado.concurrent.Future` s from blocking methods,
for use in coroutines and async applications.

```{seealso}
{class}`zmq.Socket` for the inherited API.
```

```{eval-rst}
.. autoclass:: Socket

  .. automethod:: recv
      :noindex:
  .. automethod:: recv_multipart
      :noindex:
  .. automethod:: send
      :noindex:
  .. automethod:: send_multipart
      :noindex:
  .. automethod:: poll
      :noindex:

```

### {class}`Poller`

Poller subclass that returns {class}`~tornado.concurrent.Future` s from poll,
for use in coroutines and async applications.

```{seealso}
{class}`zmq.Poller` for the inherited API.
```

```{eval-rst}
.. autoclass:: Poller

  .. automethod:: poll
      :noindex:
```