venv

.venv/lib/python3.12/site-packages/zmq/devices/__init__.py

@@ -0,0 +1,28 @@
+"""0MQ Device classes for running in background threads or processes."""
+
+# Copyright (C) PyZMQ Developers
+# Distributed under the terms of the Modified BSD License.
+
+from zmq import device
+from zmq.devices import (
+    basedevice,
+    monitoredqueue,
+    monitoredqueuedevice,
+    proxydevice,
+    proxysteerabledevice,
+)
+from zmq.devices.basedevice import *
+from zmq.devices.monitoredqueue import *
+from zmq.devices.monitoredqueuedevice import *
+from zmq.devices.proxydevice import *
+from zmq.devices.proxysteerabledevice import *
+
+__all__ = ['device']
+for submod in (
+    basedevice,
+    proxydevice,
+    proxysteerabledevice,
+    monitoredqueue,
+    monitoredqueuedevice,
+):
+    __all__.extend(submod.__all__)  # type: ignore

.venv/lib/python3.12/site-packages/zmq/devices/basedevice.py

@@ -0,0 +1,310 @@
+"""Classes for running 0MQ Devices in the background."""
+
+# Copyright (C) PyZMQ Developers
+# Distributed under the terms of the Modified BSD License.
+
+import time
+from multiprocessing import Process
+from threading import Thread
+from typing import Any, Callable, List, Optional, Tuple
+
+import zmq
+from zmq import ENOTSOCK, ETERM, PUSH, QUEUE, Context, ZMQBindError, ZMQError, device
+
+
+class Device:
+    """A 0MQ Device to be run in the background.
+
+    You do not pass Socket instances to this, but rather Socket types::
+
+        Device(device_type, in_socket_type, out_socket_type)
+
+    For instance::
+
+        dev = Device(zmq.QUEUE, zmq.DEALER, zmq.ROUTER)
+
+    Similar to zmq.device, but socket types instead of sockets themselves are
+    passed, and the sockets are created in the work thread, to avoid issues
+    with thread safety. As a result, additional bind_{in|out} and
+    connect_{in|out} methods and setsockopt_{in|out} allow users to specify
+    connections for the sockets.
+
+    Parameters
+    ----------
+    device_type : int
+        The 0MQ Device type
+    {in|out}_type : int
+        zmq socket types, to be passed later to context.socket(). e.g.
+        zmq.PUB, zmq.SUB, zmq.REQ. If out_type is < 0, then in_socket is used
+        for both in_socket and out_socket.
+
+    Methods
+    -------
+    bind_{in_out}(iface)
+        passthrough for ``{in|out}_socket.bind(iface)``, to be called in the thread
+    connect_{in_out}(iface)
+        passthrough for ``{in|out}_socket.connect(iface)``, to be called in the
+        thread
+    setsockopt_{in_out}(opt,value)
+        passthrough for ``{in|out}_socket.setsockopt(opt, value)``, to be called in
+        the thread
+
+    Attributes
+    ----------
+    daemon : bool
+        sets whether the thread should be run as a daemon
+        Default is true, because if it is false, the thread will not
+        exit unless it is killed
+    context_factory : callable
+        This is a class attribute.
+        Function for creating the Context. This will be Context.instance
+        in ThreadDevices, and Context in ProcessDevices.  The only reason
+        it is not instance() in ProcessDevices is that there may be a stale
+        Context instance already initialized, and the forked environment
+        should *never* try to use it.
+    """
+
+    context_factory: Callable[[], zmq.Context] = Context.instance
+    """Callable that returns a context. Typically either Context.instance or Context,
+    depending on whether the device should share the global instance or not.
+    """
+
+    daemon: bool
+    device_type: int
+    in_type: int
+    out_type: int
+
+    _in_binds: List[str]
+    _in_connects: List[str]
+    _in_sockopts: List[Tuple[int, Any]]
+    _out_binds: List[str]
+    _out_connects: List[str]
+    _out_sockopts: List[Tuple[int, Any]]
+    _random_addrs: List[str]
+    _sockets: List[zmq.Socket]
+
+    def __init__(
+        self,
+        device_type: int = QUEUE,
+        in_type: Optional[int] = None,
+        out_type: Optional[int] = None,
+    ) -> None:
+        self.device_type = device_type
+        if in_type is None:
+            raise TypeError("in_type must be specified")
+        if out_type is None:
+            raise TypeError("out_type must be specified")
+        self.in_type = in_type
+        self.out_type = out_type
+        self._in_binds = []
+        self._in_connects = []
+        self._in_sockopts = []
+        self._out_binds = []
+        self._out_connects = []
+        self._out_sockopts = []
+        self._random_addrs = []
+        self.daemon = True
+        self.done = False
+        self._sockets = []
+
+    def bind_in(self, addr: str) -> None:
+        """Enqueue ZMQ address for binding on in_socket.
+
+        See zmq.Socket.bind for details.
+        """
+        self._in_binds.append(addr)
+
+    def bind_in_to_random_port(self, addr: str, *args, **kwargs) -> int:
+        """Enqueue a random port on the given interface for binding on
+        in_socket.
+
+        See zmq.Socket.bind_to_random_port for details.
+
+        .. versionadded:: 18.0
+        """
+        port = self._reserve_random_port(addr, *args, **kwargs)
+
+        self.bind_in(f'{addr}:{port}')
+
+        return port
+
+    def connect_in(self, addr: str) -> None:
+        """Enqueue ZMQ address for connecting on in_socket.
+
+        See zmq.Socket.connect for details.
+        """
+        self._in_connects.append(addr)
+
+    def setsockopt_in(self, opt: int, value: Any) -> None:
+        """Enqueue setsockopt(opt, value) for in_socket
+
+        See zmq.Socket.setsockopt for details.
+        """
+        self._in_sockopts.append((opt, value))
+
+    def bind_out(self, addr: str) -> None:
+        """Enqueue ZMQ address for binding on out_socket.
+
+        See zmq.Socket.bind for details.
+        """
+        self._out_binds.append(addr)
+
+    def bind_out_to_random_port(self, addr: str, *args, **kwargs) -> int:
+        """Enqueue a random port on the given interface for binding on
+        out_socket.
+
+        See zmq.Socket.bind_to_random_port for details.
+
+        .. versionadded:: 18.0
+        """
+        port = self._reserve_random_port(addr, *args, **kwargs)
+
+        self.bind_out(f'{addr}:{port}')
+
+        return port
+
+    def connect_out(self, addr: str):
+        """Enqueue ZMQ address for connecting on out_socket.
+
+        See zmq.Socket.connect for details.
+        """
+        self._out_connects.append(addr)
+
+    def setsockopt_out(self, opt: int, value: Any):
+        """Enqueue setsockopt(opt, value) for out_socket
+
+        See zmq.Socket.setsockopt for details.
+        """
+        self._out_sockopts.append((opt, value))
+
+    def _reserve_random_port(self, addr: str, *args, **kwargs) -> int:
+        with Context() as ctx:
+            with ctx.socket(PUSH) as binder:
+                for i in range(5):
+                    port = binder.bind_to_random_port(addr, *args, **kwargs)
+
+                    new_addr = f'{addr}:{port}'
+
+                    if new_addr in self._random_addrs:
+                        continue
+                    else:
+                        break
+                else:
+                    raise ZMQBindError("Could not reserve random port.")
+
+                self._random_addrs.append(new_addr)
+
+        return port
+
+    def _setup_sockets(self) -> Tuple[zmq.Socket, zmq.Socket]:
+        ctx: zmq.Context[zmq.Socket] = self.context_factory()  # type: ignore
+        self._context = ctx
+
+        # create the sockets
+        ins = ctx.socket(self.in_type)
+        self._sockets.append(ins)
+        if self.out_type < 0:
+            outs = ins
+        else:
+            outs = ctx.socket(self.out_type)
+            self._sockets.append(outs)
+
+        # set sockopts (must be done first, in case of zmq.IDENTITY)
+        for opt, value in self._in_sockopts:
+            ins.setsockopt(opt, value)
+        for opt, value in self._out_sockopts:
+            outs.setsockopt(opt, value)
+
+        for iface in self._in_binds:
+            ins.bind(iface)
+        for iface in self._out_binds:
+            outs.bind(iface)
+
+        for iface in self._in_connects:
+            ins.connect(iface)
+        for iface in self._out_connects:
+            outs.connect(iface)
+
+        return ins, outs
+
+    def run_device(self) -> None:
+        """The runner method.
+
+        Do not call me directly, instead call ``self.start()``, just like a Thread.
+        """
+        ins, outs = self._setup_sockets()
+        device(self.device_type, ins, outs)
+
+    def _close_sockets(self):
+        """Cleanup sockets we created"""
+        for s in self._sockets:
+            if s and not s.closed:
+                s.close()
+
+    def run(self) -> None:
+        """wrap run_device in try/catch ETERM"""
+        try:
+            self.run_device()
+        except ZMQError as e:
+            if e.errno in {ETERM, ENOTSOCK}:
+                # silence TERM, ENOTSOCK errors, because this should be a clean shutdown
+                pass
+            else:
+                raise
+        finally:
+            self.done = True
+            self._close_sockets()
+
+    def start(self) -> None:
+        """Start the device. Override me in subclass for other launchers."""
+        return self.run()
+
+    def join(self, timeout: Optional[float] = None) -> None:
+        """wait for me to finish, like Thread.join.
+
+        Reimplemented appropriately by subclasses."""
+        tic = time.monotonic()
+        toc = tic
+        while not self.done and not (timeout is not None and toc - tic > timeout):
+            time.sleep(0.001)
+            toc = time.monotonic()
+
+
+class BackgroundDevice(Device):
+    """Base class for launching Devices in background processes and threads."""
+
+    launcher: Any = None
+    _launch_class: Any = None
+
+    def start(self) -> None:
+        self.launcher = self._launch_class(target=self.run)
+        self.launcher.daemon = self.daemon
+        return self.launcher.start()
+
+    def join(self, timeout: Optional[float] = None) -> None:
+        return self.launcher.join(timeout=timeout)
+
+
+class ThreadDevice(BackgroundDevice):
+    """A Device that will be run in a background Thread.
+
+    See Device for details.
+    """
+
+    _launch_class = Thread
+
+
+class ProcessDevice(BackgroundDevice):
+    """A Device that will be run in a background Process.
+
+    See Device for details.
+    """
+
+    _launch_class = Process
+    context_factory = Context
+    """Callable that returns a context. Typically either Context.instance or Context,
+    depending on whether the device should share the global instance or not.
+    """
+
+
+__all__ = ['Device', 'ThreadDevice', 'ProcessDevice']

.venv/lib/python3.12/site-packages/zmq/devices/monitoredqueue.py

@@ -0,0 +1,51 @@
+"""pure Python monitored_queue function
+
+For use when Cython extension is unavailable (PyPy).
+
+Authors
+-------
+* MinRK
+"""
+
+# Copyright (C) PyZMQ Developers
+# Distributed under the terms of the Modified BSD License.
+
+from typing import Callable
+
+import zmq
+from zmq.backend import monitored_queue as _backend_mq
+
+
+def _relay(ins, outs, sides, prefix, swap_ids):
+    msg = ins.recv_multipart()
+    if swap_ids:
+        msg[:2] = msg[:2][::-1]
+    outs.send_multipart(msg)
+    sides.send_multipart([prefix] + msg)
+
+
+def _monitored_queue(
+    in_socket, out_socket, mon_socket, in_prefix=b'in', out_prefix=b'out'
+):
+    swap_ids = in_socket.type == zmq.ROUTER and out_socket.type == zmq.ROUTER
+
+    poller = zmq.Poller()
+    poller.register(in_socket, zmq.POLLIN)
+    poller.register(out_socket, zmq.POLLIN)
+    while True:
+        events = dict(poller.poll())
+        if in_socket in events:
+            _relay(in_socket, out_socket, mon_socket, in_prefix, swap_ids)
+        if out_socket in events:
+            _relay(out_socket, in_socket, mon_socket, out_prefix, swap_ids)
+
+
+monitored_queue: Callable
+if _backend_mq is not None:
+    monitored_queue = _backend_mq  # type: ignore
+else:
+    # backend has no monitored_queue
+    monitored_queue = _monitored_queue
+
+
+__all__ = ['monitored_queue']

.venv/lib/python3.12/site-packages/zmq/devices/monitoredqueuedevice.py

@@ -0,0 +1,60 @@
+"""MonitoredQueue classes and functions."""
+
+# Copyright (C) PyZMQ Developers
+# Distributed under the terms of the Modified BSD License.
+
+from zmq import PUB
+from zmq.devices.monitoredqueue import monitored_queue
+from zmq.devices.proxydevice import ProcessProxy, Proxy, ProxyBase, ThreadProxy
+
+
+class MonitoredQueueBase(ProxyBase):
+    """Base class for overriding methods."""
+
+    _in_prefix = b''
+    _out_prefix = b''
+
+    def __init__(
+        self, in_type, out_type, mon_type=PUB, in_prefix=b'in', out_prefix=b'out'
+    ):
+        ProxyBase.__init__(self, in_type=in_type, out_type=out_type, mon_type=mon_type)
+
+        self._in_prefix = in_prefix
+        self._out_prefix = out_prefix
+
+    def run_device(self):
+        ins, outs, mons = self._setup_sockets()
+        monitored_queue(ins, outs, mons, self._in_prefix, self._out_prefix)
+
+
+class MonitoredQueue(MonitoredQueueBase, Proxy):
+    """Class for running monitored_queue in the background.
+
+    See zmq.devices.Device for most of the spec. MonitoredQueue differs from Proxy,
+    only in that it adds a ``prefix`` to messages sent on the monitor socket,
+    with a different prefix for each direction.
+
+    MQ also supports ROUTER on both sides, which zmq.proxy does not.
+
+    If a message arrives on `in_sock`, it will be prefixed with `in_prefix` on the monitor socket.
+    If it arrives on out_sock, it will be prefixed with `out_prefix`.
+
+    A PUB socket is the most logical choice for the mon_socket, but it is not required.
+    """
+
+
+class ThreadMonitoredQueue(MonitoredQueueBase, ThreadProxy):
+    """Run zmq.monitored_queue in a background thread.
+
+    See MonitoredQueue and Proxy for details.
+    """
+
+
+class ProcessMonitoredQueue(MonitoredQueueBase, ProcessProxy):
+    """Run zmq.monitored_queue in a separate process.
+
+    See MonitoredQueue and Proxy for details.
+    """
+
+
+__all__ = ['MonitoredQueue', 'ThreadMonitoredQueue', 'ProcessMonitoredQueue']

.venv/lib/python3.12/site-packages/zmq/devices/proxydevice.py

@@ -0,0 +1,104 @@
+"""Proxy classes and functions."""
+
+# Copyright (C) PyZMQ Developers
+# Distributed under the terms of the Modified BSD License.
+
+import zmq
+from zmq.devices.basedevice import Device, ProcessDevice, ThreadDevice
+
+
+class ProxyBase:
+    """Base class for overriding methods."""
+
+    def __init__(self, in_type, out_type, mon_type=zmq.PUB):
+        Device.__init__(self, in_type=in_type, out_type=out_type)
+        self.mon_type = mon_type
+        self._mon_binds = []
+        self._mon_connects = []
+        self._mon_sockopts = []
+
+    def bind_mon(self, addr):
+        """Enqueue ZMQ address for binding on mon_socket.
+
+        See zmq.Socket.bind for details.
+        """
+        self._mon_binds.append(addr)
+
+    def bind_mon_to_random_port(self, addr, *args, **kwargs):
+        """Enqueue a random port on the given interface for binding on
+        mon_socket.
+
+        See zmq.Socket.bind_to_random_port for details.
+
+        .. versionadded:: 18.0
+        """
+        port = self._reserve_random_port(addr, *args, **kwargs)
+
+        self.bind_mon(f'{addr}:{port}')
+
+        return port
+
+    def connect_mon(self, addr):
+        """Enqueue ZMQ address for connecting on mon_socket.
+
+        See zmq.Socket.connect for details.
+        """
+        self._mon_connects.append(addr)
+
+    def setsockopt_mon(self, opt, value):
+        """Enqueue setsockopt(opt, value) for mon_socket
+
+        See zmq.Socket.setsockopt for details.
+        """
+        self._mon_sockopts.append((opt, value))
+
+    def _setup_sockets(self):
+        ins, outs = Device._setup_sockets(self)
+        ctx = self._context
+        mons = ctx.socket(self.mon_type)
+        self._sockets.append(mons)
+
+        # set sockopts (must be done first, in case of zmq.IDENTITY)
+        for opt, value in self._mon_sockopts:
+            mons.setsockopt(opt, value)
+
+        for iface in self._mon_binds:
+            mons.bind(iface)
+
+        for iface in self._mon_connects:
+            mons.connect(iface)
+
+        return ins, outs, mons
+
+    def run_device(self):
+        ins, outs, mons = self._setup_sockets()
+        zmq.proxy(ins, outs, mons)
+
+
+class Proxy(ProxyBase, Device):
+    """Threadsafe Proxy object.
+
+    See zmq.devices.Device for most of the spec. This subclass adds a
+    <method>_mon version of each <method>_{in|out} method, for configuring the
+    monitor socket.
+
+    A Proxy is a 3-socket ZMQ Device that functions just like a
+    QUEUE, except each message is also sent out on the monitor socket.
+
+    A PUB socket is the most logical choice for the mon_socket, but it is not required.
+    """
+
+
+class ThreadProxy(ProxyBase, ThreadDevice):
+    """Proxy in a Thread. See Proxy for more."""
+
+
+class ProcessProxy(ProxyBase, ProcessDevice):
+    """Proxy in a Process. See Proxy for more."""
+
+
+__all__ = [
+    'Proxy',
+    'ThreadProxy',
+    'ProcessProxy',
+]

.venv/lib/python3.12/site-packages/zmq/devices/proxysteerabledevice.py

@@ -0,0 +1,106 @@
+"""Classes for running a steerable ZMQ proxy"""
+
+# Copyright (C) PyZMQ Developers
+# Distributed under the terms of the Modified BSD License.
+
+import zmq
+from zmq.devices.proxydevice import ProcessProxy, Proxy, ThreadProxy
+
+
+class ProxySteerableBase:
+    """Base class for overriding methods."""
+
+    def __init__(self, in_type, out_type, mon_type=zmq.PUB, ctrl_type=None):
+        super().__init__(in_type=in_type, out_type=out_type, mon_type=mon_type)
+        self.ctrl_type = ctrl_type
+        self._ctrl_binds = []
+        self._ctrl_connects = []
+        self._ctrl_sockopts = []
+
+    def bind_ctrl(self, addr):
+        """Enqueue ZMQ address for binding on ctrl_socket.
+
+        See zmq.Socket.bind for details.
+        """
+        self._ctrl_binds.append(addr)
+
+    def bind_ctrl_to_random_port(self, addr, *args, **kwargs):
+        """Enqueue a random port on the given interface for binding on
+        ctrl_socket.
+
+        See zmq.Socket.bind_to_random_port for details.
+        """
+        port = self._reserve_random_port(addr, *args, **kwargs)
+
+        self.bind_ctrl(f'{addr}:{port}')
+
+        return port
+
+    def connect_ctrl(self, addr):
+        """Enqueue ZMQ address for connecting on ctrl_socket.
+
+        See zmq.Socket.connect for details.
+        """
+        self._ctrl_connects.append(addr)
+
+    def setsockopt_ctrl(self, opt, value):
+        """Enqueue setsockopt(opt, value) for ctrl_socket
+
+        See zmq.Socket.setsockopt for details.
+        """
+        self._ctrl_sockopts.append((opt, value))
+
+    def _setup_sockets(self):
+        ins, outs, mons = super()._setup_sockets()
+        ctx = self._context
+        ctrls = ctx.socket(self.ctrl_type)
+        self._sockets.append(ctrls)
+
+        for opt, value in self._ctrl_sockopts:
+            ctrls.setsockopt(opt, value)
+
+        for iface in self._ctrl_binds:
+            ctrls.bind(iface)
+
+        for iface in self._ctrl_connects:
+            ctrls.connect(iface)
+
+        return ins, outs, mons, ctrls
+
+    def run_device(self):
+        ins, outs, mons, ctrls = self._setup_sockets()
+        zmq.proxy_steerable(ins, outs, mons, ctrls)
+
+
+class ProxySteerable(ProxySteerableBase, Proxy):
+    """Class for running a steerable proxy in the background.
+
+    See zmq.devices.Proxy for most of the spec.  If the control socket is not
+    NULL, the proxy supports control flow, provided by the socket.
+
+    If PAUSE is received on this socket, the proxy suspends its activities. If
+    RESUME is received, it goes on. If TERMINATE is received, it terminates
+    smoothly.  If the control socket is NULL, the proxy behave exactly as if
+    zmq.devices.Proxy had been used.
+
+    This subclass adds a <method>_ctrl version of each <method>_{in|out}
+    method, for configuring the control socket.
+
+    .. versionadded:: libzmq-4.1
+    .. versionadded:: 18.0
+    """
+
+
+class ThreadProxySteerable(ProxySteerableBase, ThreadProxy):
+    """ProxySteerable in a Thread. See ProxySteerable for details."""
+
+
+class ProcessProxySteerable(ProxySteerableBase, ProcessProxy):
+    """ProxySteerable in a Process. See ProxySteerable for details."""
+
+
+__all__ = [
+    'ProxySteerable',
+    'ThreadProxySteerable',
+    'ProcessProxySteerable',
+]