PyZMQ

https://github.com/zeromq/pyzmq
Admin
PyZMQ provides Python bindings for ZeroMQ, a lightweight and fast messaging system for building...
Tokens:90,658
Snippets:769
Trust Score:7.6
License:BSD-3-Clause
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Context option examples for get and set

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.md

These are example options for Context.get and Context.set. Available values depend on your libzmq version.

```default
zmq.IO_THREADS, zmq.MAX_SOCKETS
```

--------------------------------

### Start log watcher for complete example

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/logging.md

Starts the log watcher with the root topic 'greeter' and aligns the output. The endpoint is given as a positional argument.

```default
python -m zmq.log -t greeter --align tcp://127.0.0.1:12345
```

--------------------------------

### Project hierarchy for complete example

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/logging.md

Shows the file layout for the complete example: example.py, greetings.py, and hello.py in the same directory.

```default
example.py
greetings.py
hello.py
```

--------------------------------

### Install pre-commit

Source: https://github.com/zeromq/pyzmq/blob/main/CONTRIBUTING.md

Install pre-commit for autoformatting. Run these commands in the project root to set up the pre-commit hooks.

```bash
pip install pre-commit
pre-commit install
```

--------------------------------

### Install libzmq with draft support

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/draft.md

Use this bash script to download, configure, and install libzmq with DRAFT API support. It sets the ZMQ_VERSION and PREFIX variables, downloads the tarball, extracts it, configures with --enable-drafts, and installs. The CPU_COUNT variable is used to parallelize the build.

```bash
ZMQ_VERSION=4.3.5
PREFIX=/usr/local
CPU_COUNT=${CPU_COUNT:-$(python3 -c "import os; print(os.cpu_count())")}


wget https://github.com/zeromq/libzmq/releases/download/v${ZMQ_VERSION}/zeromq-${ZMQ_VERSION}.tar.gz -O libzmq.tar.gz
tar -xzf libzmq.tar.gz
cd zeromq-${ZMQ_VERSION}
./configure --prefix=${PREFIX} --enable-drafts
make -j${CPU_COUNT} && make install
sudo ldconfig
```

--------------------------------

### Build and run Cython example

Source: https://github.com/zeromq/pyzmq/blob/main/examples/cython/README.md

Builds the Cython extension in place and runs the example with 100000 messages, producing throughput measurements for both the Python API and the Cython API.

```bash
python setup.py build_ext --inplace
python example.py -n 100000
```

--------------------------------

### Install pyzmq from source with pip (--no-binary)

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/build.md

Build and install pyzmq from source, forcing a source build rather than using a pre-built wheel.

```default
python3 -m pip install pyzmq --no-binary pyzmq
```

--------------------------------

### Install 32-bit compatibility libraries

Source: https://github.com/zeromq/pyzmq/wiki/Cross-compiling-PyZMQ-for-Android

Install 32-bit compatibility libraries on a 64-bit host OS to support the Android NDK toolchain.

```bash
sudo apt-get install ia32-libs
```

--------------------------------

### Editable install from local checkout

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/build.md

Install pyzmq in editable mode from a local source checkout, useful for development.

```default
python3 -m pip install -e .
```

--------------------------------

### Install Android toolchain and set compiler environment

Source: https://github.com/zeromq/pyzmq/wiki/Cross-compiling-PyZMQ-for-Android

Download and install the Android NDK standalone toolchain, then set the compiler environment variables for cross-compilation.

```bash
cd "$ROOT"
NDK="android-ndk-r8d"
NDKTAR="$NDK-linux-x86.tar.bz2"
if [ ! -d $NDK ]; then
    if [ ! -e $NDKTAR ]; then
	wget -c http://dl.google.com/android/ndk/$NDKTAR
    fi
    tar xfj $NDKTAR
fi
sudo ./$NDK/build/tools/make-standalone-toolchain.sh --install-dir=/opt/android-toolchain
export PATH=/opt/android-toolchain/bin:$PATH
export CC="arm-linux-androideabi-gcc"
export LDSHARED="arm-linux-androideabi-gcc -shared"
```

--------------------------------

### Install PyZMQ with pip

Source: https://github.com/zeromq/pyzmq/blob/main/README.md

Install the latest PyZMQ binary wheel from PyPI. This should work on macOS, Windows, and Linux. Ensure you have the latest pip to get the correct wheel.

```bash
pip install pyzmq
```

--------------------------------

### AsyncioAuthenticator.start

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.auth.asyncio.md

Start ZAP authentication.

```APIDOC
## AsyncioAuthenticator.start

### Description
Start ZAP authentication.

### Method
start

### Signature
start() -> None
```

--------------------------------

### Install test requirements

Source: https://github.com/zeromq/pyzmq/wiki/Building-and-Installing-PyZMQ

Installs the test dependencies required to run the pyzmq test suite.

```bash
$ pip install -r test-requirements
```

--------------------------------

### Create a Device with QUEUE, DEALER, ROUTER

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.devices.md

Example of creating a Device instance with zmq.QUEUE, zmq.DEALER, and zmq.ROUTER socket types.

```python
dev = Device(zmq.QUEUE, zmq.DEALER, zmq.ROUTER)
```

--------------------------------

### Log with topic and exc_info

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.log.handlers.md

Example of using the log method with a topic and exc_info keyword argument.

```default
logger.log(level, "zmq.fun", "We have a %s",
        "mysterious problem", exc_info=1)
```

--------------------------------

### Example throughput output

Source: https://github.com/zeromq/pyzmq/blob/main/examples/cython/README.md

Example output showing throughput measurements for Cython and Python APIs, with Cython achieving higher messages per second.

```text
Sending 5000000 messages on tcp://127.0.0.1:5555 with Cython
Cython:    2061989 msgs/sec
Sending 5000000 messages on tcp://127.0.0.1:5555 with Python
Python:     857856 msgs/sec
```

--------------------------------

### Install pyzmq in editable mode for development

Source: https://github.com/zeromq/pyzmq/wiki/Building-and-Installing-PyZMQ

Installs pyzmq in editable mode for development, building the C extension inplace and adding the directory to sys.path. Requires Cython 0.29 or greater.

```bash
$ pip install -e .
```

--------------------------------

### Install libzmq system dependencies (apt, yum, brew)

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/build.md

Install libzmq development packages for Debian-based, Fedora-based, and macOS (homebrew) systems. Required before building pyzmq from source.

```bash
# Debian-based
sudo apt-get install libzmq3-dev

# Fedora-based
sudo yum install libzmq3-devel

# homebrew
brew install zeromq
```

--------------------------------

### Example output of version information

Source: https://github.com/zeromq/pyzmq/blob/main/CONTRIBUTING.md

This is the expected output from the version information snippet, showing the libzmq, pyzmq, and Python versions. It serves as a reference for what the output should look like.

```text
libzmq-4.3.4
pyzmq-22.3.0
Python-3.9.9 | packaged by conda-forge | (main, Dec 20 2021, 02:38:53)
[Clang 11.1.0 ]
```

--------------------------------

### Full CURVE security example

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/curve.md

Complete working example of two sockets connected with CURVE security. The client will not receive a message if CURVE is not configured correctly.

```python
import zmq

url = "tcp://127.0.0.1:5555"
ctx = zmq.Context()
server_public, server_secret = zmq.curve_keypair()

# setup server socket (curve_server=True)
server = ctx.socket(zmq.PUSH)
server.curve_server = True
server.curve_secretkey = server_secret
server.bind(url)

# setup client socket (sets curve_serverkey)
client = ctx.socket(zmq.PULL)
client.curve_serverkey = server_public
client.curve_publickey, client.curve_secretkey = zmq.curve_keypair()
client.connect(url)

server.send(b"message")
client.recv()  # will not get a message if CURVE is not configured correctly
```

--------------------------------

### Build wheel against installed libzmq (ZMQ_PREFIX)

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/build.md

Build a wheel using an already-installed libzmq by setting ZMQ_PREFIX to its prefix. The build will use that libzmq instead of searching.

```bash
export ZMQ_PREFIX=/usr/local
python3 -m pip install pyzmq --no-binary pyzmq
```

--------------------------------

### Install pyzmq with custom ZMQ_PREFIX

Source: https://github.com/zeromq/pyzmq/wiki/Building-and-Installing-PyZMQ

Specifies a custom libzmq prefix via the ZMQ_PREFIX environment variable, skipping the search for a system libzmq. Use when libzmq is installed in a non-standard location.

```bash
ZMQ_PREFIX=/opt/my/zmq-prefix pip install --no-binary pyzmq
```

--------------------------------

### get(option: int)

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.md

Gets the value of a socket option.

```APIDOC
## get(option: int)

### Description
Gets the value of a socket option. See the 0MQ API documentation for details on specific options.

### Method
get

### Parameters
#### Parameters
- **option** (int) - Required - The option to get. Available values depend on your version of libzmq. Examples include: `zmq.IDENTITY, HWM, LINGER, FD, EVENTS`.

### Returns
- **optval** (int or bytes) - The value of the option as a bytestring or int.

### Versionchanged
Changed in version 27: Added experimental support for ZMQ_FD for draft sockets via `zmq_poller_fd`. Requires libzmq >=4.3.2 built with draft support.
```

--------------------------------

### Force source installation of PyZMQ

Source: https://github.com/zeromq/pyzmq/blob/main/README.md

Force PyZMQ to compile from source, bypassing binary wheels. Useful if the wheel fails or you want to link against a custom libzmq installation.

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

--------------------------------

### Install pyzmq from source ignoring wheels

Source: https://github.com/zeromq/pyzmq/wiki/Building-and-Installing-PyZMQ

Forces a source build of pyzmq, ignoring pre-built wheels. Useful when binary installers fail or when you need to link against a system libzmq.

```bash
pip install --no-binary pyzmq pyzmq
```

--------------------------------

### Install pyzmq with bundled libzmq

Source: https://github.com/zeromq/pyzmq/wiki/Building-and-Installing-PyZMQ

Tells pyzmq to build libzmq as a Python extension (bundled) instead of linking against a system libzmq. Use when you want a self-contained build.

```bash
ZMQ_PREFIX=bundled pip install --no-binary pyzmq pyzmq
```

--------------------------------

### Set pyzmq build options via CMAKE_ARGS

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/build.md

Passes the same options as the previous example via the CMAKE_ARGS environment variable, using semicolons to separate list values. Equivalent to setting the options individually.

```bash
export CMAKE_ARGS="-DZMQ_PREFIX=bundled -DPYZMQ_LIBZMQ_VERSION=4.3.4 -DPYZMQ_LIBSODIUM_CONFIGURE_ARGS=--disable-pie;--minimal"
python3 -m build .

```

--------------------------------

### Basic asyncio usage with zmq.asyncio

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.asyncio.md

Shows how to create an asyncio context and use a PULL socket with await on recv_multipart and send_multipart. Requires Python 3 and asyncio. The example binds to a URL and processes messages asynchronously.

```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())
```

--------------------------------

### ThreadAuthenticator.start

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.auth.thread.md

Starts the authentication thread.

```APIDOC
## ThreadAuthenticator.start

### Description
Start the authentication thread.

### Method
start

### Parameters
None

### Returns
None

### Example
```python
authenticator.start()
```
```

--------------------------------

### zmq.proxy_steerable(frontend, backend, capture=None, control=None)

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.devices.md

Starts a ZeroMQ proxy with control flow. Allows control of the proxy via a control socket.

```APIDOC
## zmq.proxy_steerable(frontend, backend, capture=None, control=None)

### Description
Start a zeromq proxy with control flow.

### Method
Function call

### Signature
`zmq.proxy_steerable(frontend: Socket, backend: Socket, capture: Socket = None, control: Socket = None)`

### Parameters
- **frontend** (Socket) - Required - The Socket instance for the incoming traffic.
- **backend** (Socket) - Required - The Socket instance for the outbound traffic.
- **capture** (Socket, optional) - Optional - The Socket instance for capturing traffic.
- **control** (Socket, optional) - Optional - The Socket instance for control flow.

### Version Added
Added in version libzmq-4.1.
Added in version 18.0.

```

--------------------------------

### Get python-lib

Source: https://github.com/zeromq/pyzmq/wiki/Cross-compiling-PyZMQ-for-Android

Download and extract the python-lib package needed for building pyzmq for Android.

```bash
cd "$ROOT"
wget http://python-for-android.googlecode.com/files/python-lib_r16.zip
unzip python-lib_r16.zip -dpython-lib
```

--------------------------------

### Build pyzmq with draft support

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/draft.md

Use this bash script to build pyzmq from source with DRAFT API support. It sets the ZMQ_PREFIX and ZMQ_DRAFT_API environment variables, optionally adds an rpath to find libzmq at runtime, and installs pyzmq using pip with --no-binary to force compilation from source.

```bash
export ZMQ_PREFIX=${PREFIX}
export ZMQ_DRAFT_API=1
# rpath may be needed to find libzmq at runtime,
# depending on installation
export LDFLAGS="${LDFLAGS:-} -Wl,-rpath,${ZMQ_PREFIX}/lib"
pip install -v pyzmq --no-binary pyzmq
```

--------------------------------

### Create PUBHandler with socket or interface

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.log.handlers.md

Two equivalent ways to create a PUBHandler: either pass an already-bound PUB socket or pass an interface string to bind to. The first example binds an inproc socket, the second passes the interface directly.

```default
sock = context.socket(zmq.PUB)
sock.bind('inproc://log')
handler = PUBHandler(sock)
```

```default
handler = PUBHandler('inproc://loc')
```

--------------------------------

### Launch a ProcessDevice in the background

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/devices.md

Creates a ProcessDevice with QUEUE, ROUTER, and DEALER socket types, configures the in/out sockets via proxy methods, and starts it in a background process.

```python
from zmq.devices import ProcessDevice

pd = ProcessDevice(zmq.QUEUE, zmq.ROUTER, zmq.DEALER)
pd.bind_in('tcp://*:12345')
pd.connect_out('tcp://127.0.0.1:12543')
pd.setsockopt_in(zmq.IDENTITY, 'ROUTER')
pd.setsockopt_out(zmq.IDENTITY, 'DEALER')
pd.start()
# it will now be running in a background process
```

--------------------------------

### Configure PUBHandler for logging

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/logging.md

Configure logging in your Python module and set up the ZMQ log handler. Add the handler once in the top-level module on the root logger. Choose any IP address and port that works on your system; the example uses tcp://127.0.0.1:12345.

```default
import logging
from zmq.log.handlers import PUBHandler

zmq_log_handler = PUBHandler('tcp://127.0.0.1:12345')
logger = logging.getLogger()
logger.addHandler(zmq_log_handler)
```

--------------------------------

### monitor(addr: str | bytes | None, events: int = 65535)

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.md

Starts publishing socket events on inproc.

```APIDOC
## monitor(addr: str | bytes | None, events: int = 65535)

### Description
Starts publishing socket events on inproc. See libzmq docs for zmq_monitor for details. While this function is available from libzmq 3.2, pyzmq cannot parse monitor messages from libzmq prior to 4.0.

### Method
monitor

### Parameters
#### Parameters
- **addr** (str | None) - Required - The inproc url used for monitoring. Passing None as the addr will cause an existing socket monitor to be deregistered.
- **events** (int) - Optional - The zmq event bitmask for which events will be sent to the monitor. Default: zmq.EVENT_ALL.

### Versionadded
Added in version libzmq-3.2.
Added in version 14.0.
```

--------------------------------

### getsockopt(option: int)

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.md

Gets the value of a socket option.

```APIDOC
## getsockopt(option: int)

### Description
Gets the value of a socket option. See the 0MQ API documentation for details on specific options.

### Method
getsockopt

### Parameters
#### Parameters
- **option** (int) - Required - The option to get. Available values depend on your version of libzmq. Examples include: `zmq.IDENTITY, HWM, LINGER, FD, EVENTS`.

### Returns
- **optval** (int or bytes) - The value of the option as a bytestring or int.

### Versionchanged
Changed in version 27: Added experimental support for ZMQ_FD for draft sockets via `zmq_poller_fd`. Requires libzmq >=4.3.2 built with draft support.
```

--------------------------------

### zmq.proxy(frontend, backend, capture=None)

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.devices.md

Starts a ZeroMQ proxy (replacement for device). Routes messages between frontend and backend sockets, optionally capturing traffic.

```APIDOC
## zmq.proxy(frontend, backend, capture=None)

### Description
Start a zeromq proxy (replacement for device).

### Method
Function call

### Signature
`zmq.proxy(frontend: Socket, backend: Socket, capture: Socket = None)`

### Parameters
- **frontend** (Socket) - Required - The Socket instance for the incoming traffic.
- **backend** (Socket) - Required - The Socket instance for the outbound traffic.
- **capture** (Socket, optional) - Optional - The Socket instance for capturing traffic.

### Version Added
Added in version libzmq-3.2.
Added in version 13.0.

```

--------------------------------

### get_hwm() → int

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.md

Gets the High Water Mark for the socket.

```APIDOC
## get_hwm() → int

### Description
Gets the High Water Mark. On libzmq ≥ 3, this gets SNDHWM if available, otherwise RCVHWM.

### Method
get_hwm

### Parameters
None

### Returns
- **int** - The High Water Mark value.
```

--------------------------------

### Subscribe to topics with SUBSCRIBE sockopt

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/logging.md

Sets up a SUB socket to subscribe to multiple topics. The SUB socket only receives messages whose first part starts with one of the subscribed topics; the default is to exclude all messages, and subscribing to an empty string receives all messages.

```default
sub = ctx.socket(zmq.SUB)
sub.setsockopt(zmq.SUBSCRIBE, 'topic1')
sub.setsockopt(zmq.SUBSCRIBE, 'topic2')
```

--------------------------------

### Generate CURVE keypair from command line

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.md

Command-line utility to generate a CURVE keypair, available starting with pyzmq 27.2. Optionally output as JSON with the --json flag.

```bash
python3 -m zmq.curve_keygen [--json]
```

--------------------------------

### Dockerfile for building for android-aarch64 on x86_64

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/build.md

Use this Dockerfile to create a build environment for cross-compiling pyzmq for Android aarch64 on an x86_64 host. It installs required tools, builds a 'build' Python, cross-compiles libsodium and libzmq, sets up a crossenv, and builds a pyzmq wheel. The resulting wheel is placed in /src/pyzmq-$VERSION/dist/.

```Dockerfile
FROM ubuntu:22.04
RUN apt-get -y update \
 && apt-get -y install curl unzip cmake ninja-build openssl xz-utils build-essential libz-dev libssl-dev

ENV BUILD_PREFIX=/opt/build
ENV PATH=${BUILD_PREFIX}/bin:$PATH

ARG PYTHON_VERSION=3.11.8
WORKDIR /src
RUN curl -L -o python.tar.xz https://www.python.org/ftp/python/${PYTHON_VERSION}/Python-${PYTHON_VERSION}.tar.xz \
 && tar -xf python.tar.xz \
 && rm python.tar.xz \
 && mv Python-* cpython

# build our 'build' python
WORKDIR /src/cpython
RUN ./configure --prefix=${BUILD_PREFIX}
RUN make -j4
RUN make install

# sanity check
RUN python3 -c 'import ssl' \
 && python3 -m ensurepip \
 && python3 -m pip install --upgrade pip

# get our cross-compile toolchain from NDK
WORKDIR /opt
RUN curl -L -o ndk.zip https://dl.google.com/android/repository/android-ndk-r26c-linux.zip \
 && unzip ndk.zip \
 && rm ndk.zip \
 && mv android-* ndk
ENV BUILD="x86_64-linux-gnu"
ENV HOST="aarch64-linux-android34"
ENV PATH=/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH
ENV CC=$HOST-clang \
    CXX=$HOST-clang++ \
    READELF=llvm-readelf

# build our 'host' python
WORKDIR /src/cpython
RUN make clean
ENV HOST_PREFIX=/opt/host
RUN ./configure \
    --prefix=${HOST_PREFIX} \
    --host=$HOST \
    --build=$BUILD \
    --with-build-python=$BUILD_PREFIX/bin/python3 \
    --without-ensurepip \
    ac_cv_buggy_getaddrinfo=no \
    ac_cv_file__dev_ptmx=yes \
    ac_cv_file__dev_ptc=no
RUN make -j4
RUN make install

# (optional) cross-compile libsodium, libzmq
WORKDIR /src
ENV LIBSODIUM_VERSION=1.0.20
RUN curl -L -O "https://download.libsodium.org/libsodium/releases/libsodium-${LIBSODIUM_VERSION}.tar.gz" \
 && tar -xzf libsodium-${LIBSODIUM_VERSION}.tar.gz \
 && mv libsodium-stable libsodium \
 && rm libsodium*.tar.gz

WORKDIR /src/libsodium
# need CFLAGS or libsodium >= 1.0.20 https://github.com/android/ndk/issues/1945
ENV CFLAGS="-march=armv8-a+crypto"
RUN ./configure --prefix="${HOST_PREFIX}" --host=$HOST
RUN make -j4
RUN make install

# build libzmq
WORKDIR /src
ENV LIBZMQ_VERSION=4.3.5
RUN curl -L -O "https://github.com/zeromq/libzmq/releases/download/v${LIBZMQ_VERSION}/zeromq-${LIBZMQ_VERSION}.tar.gz" \
 && tar -xzf zeromq-${LIBZMQ_VERSION}.tar.gz \
 && mv zeromq-${LIBZMQ_VERSION} zeromq
WORKDIR /src/zeromq
RUN ./configure --prefix="$HOST_PREFIX" --host=$HOST --disable-perf --disable-Werror --without-docs --enable-curve --with-libsodium=$HOST_PREFIX --disable-drafts --disable-libsodium_randombytes_close
RUN make -j4
RUN make install

# setup crossenv
ENV CROSS_PREFIX=/opt/cross
RUN python3 -m pip install crossenv \
 && python3 -m crossenv ${HOST_PREFIX}/bin/python3 ${CROSS_PREFIX}
ENV PATH=${CROSS_PREFIX}/bin:$PATH

# install build dependencies in crossenv
RUN . ${CROSS_PREFIX}/bin/activate \
 && build-pip install build pyproject_metadata scikit-build-core pathspec cython

ENV ZMQ_PREFIX=${HOST_PREFIX}
# if pyzmq is bundling libsodium, tell it to cross-compile
# not required if libzmq is already installed
ENV PYZMQ_LIBSODIUM_CONFIGURE_ARGS="--host $HOST"
ARG PYZMQ_VERSION=26.0.0b2
# build wheel of pyzmq
WORKDIR /src
RUN python3 -m pip download --no-binary pyzmq --pre pyzmq==$PYZMQ_VERSION \
 && tar -xzf pyzmq-*.tar.gz \
 && rm pyzmq-*.tar.gz \
 && . ${CROSS_PREFIX}/bin/activate \
 && cross-python -m build --no-isolation --skip-dependency-check --wheel ./pyzmq*

# there is now a pyzmq wheel in /src/pyzmq-$VERSION/dist/pyzmq-$VERSION-cp311-cp311-linux_aarch64.whl

```

--------------------------------

### getsockopt_string(option: int, encoding: str = 'utf-8') → str

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.md

Gets the value of a socket option as a unicode string.

```APIDOC
## getsockopt_string(option: int, encoding: str = 'utf-8') → str

### Description
Gets the value of a socket option as a unicode string. See the 0MQ documentation for details on specific options.

### Method
getsockopt_string

### Parameters
#### Parameters
- **option** (int) - Required - The option to retrieve.
- **encoding** (str) - Optional - The encoding to use. Default: 'utf-8'.

### Returns
- **optval** (str) - The value of the option as a unicode string.
```

--------------------------------

### get_string(option: int, encoding: str = 'utf-8') → str

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.md

Gets the value of a socket option as a unicode string.

```APIDOC
## get_string(option: int, encoding: str = 'utf-8') → str

### Description
Gets the value of a socket option as a unicode string. See the 0MQ documentation for details on specific options.

### Method
get_string

### Parameters
#### Parameters
- **option** (int) - Required - The option to retrieve.
- **encoding** (str) - Optional - The encoding to use. Default: 'utf-8'.

### Returns
- **optval** (str) - The value of the option as a unicode string.
```

--------------------------------

### Run example.py

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/logging.md

Runs the example.py script in a separate process to generate log messages.

```default
python example.py
```

--------------------------------

### example.py - main logging script

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/logging.md

Configures a PUBHandler with a custom formatter and root topic, then logs messages at different levels. The script sleeps briefly, logs a warning, sends a series of debug messages, and finally logs an info message.

```python
import logging
from time import sleep
from zmq.log.handlers import PUBHandler

from greetings import hello

zmq_log_handler = PUBHandler("tcp://127.0.0.1:12345")
zmq_log_handler.setFormatter(logging.Formatter(fmt="{name} > {message}", style="{"))
zmq_log_handler.setFormatter(
    logging.Formatter(fmt="{name} #{lineno:>3} > {message}", style="{"), logging.DEBUG
)
zmq_log_handler.setRootTopic("greeter")

logger = logging.getLogger()
logger.setLevel(logging.DEBUG)
logger.addHandler(zmq_log_handler)

if __name__ == "__main__":
    sleep(0.1)
    msg_count = 5
    logger.warning("Preparing to greet the world...")
    for i in range(1, msg_count + 1):
        logger.debug("Sending message {} of {}".format(i, msg_count))
        hello.world()
        sleep(1.0)
    logger.info("Done!")
```

--------------------------------

### Type annotations for sync Context and Socket

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.md

Use these type annotations to exclude async subclasses and get the resolved types for sync usage. The base Context() constructor returns zmq.Context[zmq.Socket[bytes]].

```python
ctx: zmq.Context[zmq.Socket[bytes]] = zmq.Context()
sock: zmq.Socket[bytes]
```

--------------------------------

### Set up root working directory and ZMQ prefix

Source: https://github.com/zeromq/pyzmq/wiki/Cross-compiling-PyZMQ-for-Android

Set up the root working directory and the ZMQ prefix environment variables used throughout the build process.

```bash
export ROOT=/tmp
export ZMQ_PREFIX="$ROOT/zeromq-android"
```

--------------------------------

### Test source distribution with python setup.py sdist

Source: https://github.com/zeromq/pyzmq/wiki/Releasing-PyZMQ

Tests the source distribution to verify MANIFEST.in file list changes.

```bash
python setup.py sdist
```

--------------------------------

### Clean build artifacts with python setup.py clean

Source: https://github.com/zeromq/pyzmq/wiki/Releasing-PyZMQ

Removes old MANIFEST, egg-info files, and dist and build directories before preparing a release.

```bash
python setup.py clean
```

--------------------------------

### Build and upload source distributions

Source: https://github.com/zeromq/pyzmq/wiki/Releasing-PyZMQ

Builds source distributions in zip and gztar formats and uploads them to PyPI.

```bash
python setup.py sdist --formats=zip,gztar upload
```

--------------------------------

### Start log watcher with custom topic

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/logging.md

Starts the log watcher with the -t flag to specify the root topic that matches the one set on the handler. The endpoint is given as a positional argument.

```default
python -m zmq.log -t custom_topic <tcp://127.0.0.1:12345>
```

--------------------------------

### Build pyzmq egg for Android

Source: https://github.com/zeromq/pyzmq/wiki/Cross-compiling-PyZMQ-for-Android

Clone pyzmq, write a setup.cfg with Android-specific build options, and build the egg using cython and setupegg.py.

```python
git clone git://github.com/zeromq/pyzmq.git
cd pyzmq
echo "
[global]
zmq_prefix = $ZMQ_PREFIX
have_sys_un_h = False

[build_ext]
libraries = python2.6
library_dirs = $ROOT/python-lib/lib
include_dirs = $ROOT/python-lib/include/python2.6

[bdist_egg]
plat-name = linux-armv
" > setup.cfg

python setup.py cython

python2.6 setupegg.py build bdist_egg
```

--------------------------------

### PUBHandler.get_name

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/api/zmq.log.handlers.md

Gets the handler name.

```APIDOC
## get_name()

### Description
Get the name of the handler.
```

--------------------------------

### Start the log watcher

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/logging.md

Start the built-in log watcher to tune in to messages broadcast by the log handler. Run from a shell with access to the pyzmq package, then run your Python module in a separate process to see messages appear.

```default
python -m zmq.log tcp://127.0.0.1:12345
```

--------------------------------

### Force bundled libzmq with draft API (ZMQ_BUILD_DRAFT)

Source: https://github.com/zeromq/pyzmq/blob/main/docs/source/howto/build.md

Force building the bundled libzmq and enable the draft API by setting ZMQ_PREFIX=bundled and ZMQ_BUILD_DRAFT=1.

```bash
export ZMQ_PREFIX=bundled
export ZMQ_BUILD_DRAFT=1
python3 -m pip install pyzmq --no-binary pyzmq
```
Tokens:
Raw