### Complete Logging Example Setup

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

A comprehensive Python script demonstrating the setup of a PUBHandler with custom formatters and root topic, and logging messages.

```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!")
```

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

### Start Log Watcher for Example

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

Command to start the zmq.log watcher process, subscribing to the 'greeter' topic.

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

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

### Basic Authenticator Setup and Handling

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

Demonstrates how to initialize an Authenticator, allow specific IP addresses, start the authenticator, and manually handle incoming ZAP messages. This is useful for running authentication in a non-threaded, non-event-loop environment.

```python
auth = zmq.Authenticator()
auth.allow("127.0.0.1")
auth.start()
while True:
    await auth.handle_zap_msg(auth.zap_socket.recv_multipart())
```

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

### Install and Install pre-commit

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

Installs the pre-commit tool and sets up the git pre-commit hook for automatic code formatting.

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

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

### Running Cython pyzmq Example

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

Execute this command to run an example that measures the performance difference between the Python API and the Cython-wrapped libzmq API.

```bash
python example.py -n 100000
```

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

### Install PyZMQ with Binary Wheel

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

Install PyZMQ using pip. This command attempts to download a pre-compiled binary wheel for your system, which is the recommended and fastest installation method.

```bash
pip install pyzmq
```

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

### Install Test Requirements

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

Before running the test suite, install all necessary dependencies by referencing the test-requirements file.

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

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

### Log Watcher Output Example

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

Example of the expected output from the log watcher process when running the complete logging example.

```text
greeter.WARNING | root > Preparing to greet the world...
greeter.DEBUG   | root # 21 > Sending message 1 of 5
greeter.INFO    | greetings.hello > hello world!
greeter.DEBUG   | root # 21 > Sending message 2 of 5
greeter.INFO    | greetings.hello > hello world!
greeter.DEBUG   | root # 21 > Sending message 3 of 5
greeter.INFO    | greetings.hello > hello world!
greeter.DEBUG   | root # 21 > Sending message 4 of 5
greeter.INFO    | greetings.hello > hello world!
greeter.DEBUG   | root # 21 > Sending message 5 of 5
greeter.INFO    | greetings.hello > hello world!
greeter.INFO    | root > Done!
```

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

### Install 32-bit Compatibility Libraries

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

Installs 32-bit compatibility libraries on a 64-bit host OS, which may be required for cross-compilation.

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

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

### Install libzmq with Draft Support

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

Compile and install libzmq from source with draft API support enabled. This ensures the underlying library has the necessary features for DRAFT sockets.

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

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

### device()

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

Start a ZeroMQ device.

```APIDOC
## device(device_type, frontend_type, backend_type)

### Description
Start a ZeroMQ device.

### Parameters
#### Path Parameters
- **device_type** (int) - Required - The type of device to start.
- **frontend_type** (int) - Required - The type of the frontend socket.
- **backend_type** (int) - Required - The type of the backend socket.

### Returns
None
```

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

### Build and Install libzmq for Android

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

Clones the zeromq3-x repository, configures it for cross-compilation targeting arm-linux-androideabi with specific CFLAGS and LIBS, and then builds and installs it to the specified prefix.

```bash
cd "$ROOT"
git clone git://github.com/zeromq/zeromq3-x.git
cd zeromq3-x/
./autogen.sh
./configure --host=arm-linux-androideabi --prefix="$ZMQ_PREFIX" CPPFLAGS="-fPIC -fvisibility=default" LIBS="-lgcc"
make
make install
```

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

### proxy_steerable()

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

Start a steerable ZeroMQ proxy.

```APIDOC
## proxy_steerable(frontend, backend, control, monitor=None)

### Description
Start a steerable ZeroMQ proxy.

### Parameters
#### Path Parameters
- **frontend** (zmq.Socket) - Required - The frontend socket.
- **backend** (zmq.Socket) - Required - The backend socket.
- **control** (zmq.Socket) - Required - The control socket.
- **monitor** (zmq.Socket) - Optional - The monitor socket.

### Returns
None
```

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

### proxy()

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

Start a ZeroMQ proxy.

```APIDOC
## proxy(frontend, backend, monitor=None)

### Description
Start a ZeroMQ proxy.

### Parameters
#### Path Parameters
- **frontend** (zmq.Socket) - Required - The frontend socket.
- **backend** (zmq.Socket) - Required - The backend socket.
- **monitor** (zmq.Socket) - Optional - The monitor socket.

### Returns
None
```

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

### Install libzmq Development Headers

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

Install the necessary development headers for libzmq on Debian-based, Fedora-based, or macOS systems.

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

# Fedora-based
sudo yum install libzmq3-devel

# homebrew
brew install zeromq
```

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

### AsyncioAuthenticator.start

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

Starts the ZAP authentication process.

```APIDOC
## AsyncioAuthenticator.start

### Description
Starts the ZAP authentication process.

### Method
start

### Returns
None
```

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

### Set Up Working Directory

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

Defines environment variables for the root working directory and the ZeroMQ installation prefix on the target Android system.

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

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

### Build pyzmq Wheel Against Installed libzmq

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

Build a pyzmq wheel against an already installed libzmq by setting the ZMQ_PREFIX environment variable.

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

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

### Editable Install pyzmq from Local Checkout

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

Perform an editable installation of pyzmq from a local source code checkout using pip.

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

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

### Install PyZMQ Extension

Source: https://github.com/zeromq/pyzmq/blob/main/CMakeLists.txt

Installs the PyZMQ extension module to the specified destination.

```cmake
install(TARGETS ${ZMQ_EXT_NAME} DESTINATION "${ZMQ_BACKEND_DEST}" COMPONENT pyzmq)
```

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

### Install PyZMQ from Source

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

Force PyZMQ to compile from source using pip. This is useful if a suitable binary wheel is not available or if you need to ensure it's built against a specific libzmq installation.

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

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

### Available Socket Options Example

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

Illustrates common socket options that can be retrieved using getsockopt. These options may vary based on the libzmq version.

```default
zmq.IDENTITY, HWM, LINGER, FD, EVENTS
```

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

### Asyncio Socket Receive and Send Example

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

Demonstrates how to create an asyncio context, set up a PULL socket, and asynchronously receive and send multipart messages. Requires importing asyncio, zmq, and zmq.asyncio.

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

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

### Install Android Standalone Toolchain

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

Downloads and installs the Android NDK and sets up a standalone toolchain for cross-compilation. It configures the PATH, CC, and LDSHARED environment variables for the ARM architecture.

```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"
```

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

### zmq.devices.ThreadDevice.start

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

Starts the device. This method is intended to be overridden by subclasses for custom launcher logic.

```APIDOC
## zmq.devices.ThreadDevice.start

### Description
Start the device. Override me in subclass for other launchers.

### Returns
None
```

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

### Install Windows SDKs

Source: https://github.com/zeromq/pyzmq/wiki/Setting-up-Windows

Installs specific Windows SDK versions required for Python 2 and Python 3 development. Note potential conflicts with redistributables.

```powershell
choco install windows-sdk-7.0
choco install windows-sdk-7.1
```

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

### Start Log Watcher with Custom Topic

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

Launch the zmq.log watcher utility, specifying a custom topic to filter messages.

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

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

### Install PyZMQ in Development Mode

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

Install PyZMQ in editable mode for development. This builds the C extension in place and adds the current directory to sys.path, allowing immediate use and modification of the code.

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

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

### get_includes()

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

Get the include directories for ZeroMQ.

```APIDOC
## get_includes()

### Description
Get the include directories for ZeroMQ.

### Returns
list: A list of include directory paths.
```

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

### Hello World Function for Logging Example

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

A simple Python module function that logs an 'hello world!' message.

```python
import logging

logger = logging.getLogger(__name__)

def world():
    logger.info('hello world!')
```

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

### Install PyZMQ Ignoring Wheels

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

Use this command to force PyZMQ to build from source, ignoring any available pre-built wheels. This is useful if you encounter issues with binary installers.

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

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

### Install Chocolatey Packages

Source: https://github.com/zeromq/pyzmq/wiki/Setting-up-Windows

Installs essential development tools and Python versions using Chocolatey. Ensure PowerShell is run as administrator.

```powershell
choco install atom git git.commandline
choco install python3 python2 python3-x86_32 python2-x86_32
```

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

### Bind PUB Socket and Create PUBHandler

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

Basic setup for broadcasting log messages using a ZMQ PUB socket and a pyzmq PUBHandler.

```bash
pub = context.socket(zmq.PUB)
pub.bind('tcp://*:12345')
handler = PUBHandler(pub)
logger = logging.getLogger()
logger.addHandler(handler)
```

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

### Create a ZMQ Context Instance

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

Get the singleton instance of the ZMQ context. This is the first step before creating any sockets.

```python
ctx = zmq.Context.instance()
```

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

### Install Visual Studio Community Edition

Source: https://github.com/zeromq/pyzmq/wiki/Setting-up-Windows

Installs Visual Studio 2015 Community Edition, which may require a reboot and modification to include C++ components for Python 3.5 development.

```powershell
choco install VisualStudio2015Community
```

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

### Configure and Build PyZMQ for Android

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

Clones the PyZMQ repository and creates a custom 'setup.cfg' file to specify the cross-compilation environment, including the ZeroMQ installation path, Python library locations, and the target platform name. It then builds the PyZMQ egg.

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

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

### get_library_dirs()

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

Get the library directories for ZeroMQ.

```APIDOC
## get_library_dirs()

### Description
Get the library directories for ZeroMQ.

### Returns
list: A list of library directory paths.
```

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

### Run PyZMQ Log Watcher

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

Start the log watcher utility from the command line to listen for ZMQ-published log messages on the specified address.

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

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

### TopicLogger Info Example

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

Logs a message with INFO severity and a specified topic. Use exc_info=True to include exception information.

```python
logger.info("Houston, we have a %s", "interesting problem", exc_info=True)
```

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

### zmq.proxy_steerable

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

Starts a ZeroMQ proxy with added control flow capabilities. This function allows for more advanced management of the proxy's behavior through a dedicated control socket.

```APIDOC
## zmq.proxy_steerable

### Description
Starts a zeromq proxy with control flow. This function enables steering of the proxy's operations via a control socket, in addition to handling frontend, backend, and capture sockets.

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

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

### Versionadded
Added in version libzmq-4.1.
Added in version 18.0.
```

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

### Dockerfile for Cross-Compiling x86_64 on aarch64

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

This Dockerfile demonstrates how to set up an environment for cross-compiling pyzmq from an aarch64 host to an x86_64 target. It includes steps for installing build tools, compiling Python for both build and host machines, and setting up cross-compilation tools.

```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
# I'm on aarch64, so use x86_64 as host
ENV BUILD="aarch64-linux-gnu"
ENV HOST="x86_64-linux-gnu"
RUN HOST_PKG=$(echo $HOST | sed s@_@-@g) \
 && apt-get -y install binutils-$HOST_PKG gcc-$HOST_PKG g++-$HOST_PKG
ENV CC=$HOST-gcc \
    CXX=$HOST-g++

# 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

WORKDIR /src

# # (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
# 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
WORKDIR /src
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

```

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

### Enable Draft APIs

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

To enable experimental and not fully supported ZeroMQ draft APIs, set the ZMQ_DRAFT_API environment variable to 1 before installing PyZMQ.

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

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

### Proxy with Capture Socket

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

Starts a ZeroMQ proxy using frontend, backend, and an optional capture socket for traffic monitoring. Added in libzmq-3.2.

```python
zmq.proxy(frontend, backend, capture)
```

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

### Fetch and Make Available Bundled libzmq

Source: https://github.com/zeromq/pyzmq/blob/main/CMakeLists.txt

Declares and makes available the bundled libzmq library using FetchContent. It specifies the URL for the library source and a prefix for its installation.

```cmake
FetchContent_Declare(bundled_libzmq
        URL ${PYZMQ_LIBZMQ_URL}
        PREFIX ${BUNDLE_DIR}
      )
      FetchContent_MakeAvailable(bundled_libzmq)
```

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

### TopicLogger Debug Example

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

Logs a message with DEBUG severity and a specified topic. Use exc_info=True to include exception information.

```python
logger.debug("Houston, we have a %s", "thorny problem", exc_info=True)
```

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

### Tornado ZMQStream Echo Server

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

This example sets up a Tornado `ZMQStream` to act as an echo server. It binds a REP socket, registers an `echo` callback using `on_recv` to send back received messages, and starts the Tornado IOLoop. Ensure `ZMQStream` and `ioloop` are imported.

```python
s = ctx.socket(zmq.REP)
s.bind("tcp://localhost:12345")
stream = ZMQStream(s)


def echo(msg):
    stream.send_multipart(msg)


stream.on_recv(echo)
ioloop.IOLoop.instance().start()
```

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

### monitor

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

Start publishing socket events on inproc. Requires libzmq >= 3.2. PyZMQ cannot parse monitor messages from libzmq prior to 4.0.

```APIDOC
## monitor

### Description
Start publishing socket events on inproc.

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

### Usage
See libzmq docs for zmq_monitor for details.
```

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

### Steerable Proxy with Control Socket

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

Starts a ZeroMQ proxy with frontend, backend, optional capture, and an additional control socket for flow management. Added in libzmq-4.1.

```python
zmq.proxy_steerable(frontend, backend, capture, control)
```

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

### 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
```

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

### Build Bundled libsodium with Configure

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

Build a static and PIC version of libsodium using the configure script, with options to customize the build.

```bash
./configure --enable-static --disable-shared --with-pic
make
make install
```

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

### Creating a Context with a shadow context

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

Demonstrates shadowing an existing context to create a new one, useful for async/sync context conversion.

```default
ctx = zmq.Context(async_ctx)
```

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

### Install Older PyZMQ Version

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

Install a PyZMQ version older than 16, which is necessary if you are using older Python versions like 2.6 or 3.2 that are no longer supported by recent PyZMQ releases.

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

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

### Bundling Libzmq and Libsodium with FetchContent

Source: https://github.com/zeromq/pyzmq/blob/main/CMakeLists.txt

Enables bundling of libzmq and libsodium using FetchContent when ZMQ_PREFIX is 'bundled'. Configures include paths and defines.

```cmake
if (ZMQ_PREFIX STREQUAL "bundled")
  message(STATUS "Bundling libzmq and libsodium")
  include(FetchContent)
  add_compile_definitions(ZMQ_STATIC=1)
  set(BUNDLE_DIR "${CMAKE_CURRENT_BINARY_DIR}/bundled")
  file(MAKE_DIRECTORY "${BUNDLE_DIR}/lib")
  include_directories(${BUNDLE_DIR}/include)
  list(PREPEND CMAKE_PREFIX_PATH ${BUNDLE_DIR})

  set(LICENSE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/licenses")
  file(MAKE_DIRECTORY "${LICENSE_DIR}")

  # libsodium

  if (MSVC)
    set(libsodium_lib "${BUNDLE_DIR}/lib/libsodium.lib")
  else()
    set(libsodium_lib "${BUNDLE_DIR}/lib/libsodium.a")
  endif()

  FetchContent_Declare(bundled_libsodium
    URL ${PYZMQ_LIBSODIUM_URL}
    PREFIX ${BUNDLE_DIR}
  )
  FetchContent_MakeAvailable(bundled_libsodium)
  configure_file("${bundled_libsodium_SOURCE_DIR}/LICENSE" "${LICENSE_DIR}/LICENSE.libsodium.txt" COPYONLY)
  # run libsodium build explicitly here, so it's available to libzmq next
  set(bundled_libsodium_include "${bundled_libsodium_SOURCE_DIR}/src/libsodium/include")
```

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

### PUBHandler Initialization and Usage

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

Demonstrates how to initialize and use the PUBHandler with the standard Python logging module and dictConfig for publishing log messages over a ZeroMQ PUB socket.

```APIDOC
## PUBHandler

### Description
A basic logging handler that emits log messages through a PUB socket. It can be initialized with an existing PUB socket or an interface to bind to.

### Class Signature
`zmq.log.handlers.PUBHandler(interface_or_socket: str | [Socket](zmq.md#zmq.Socket), context: [Context](zmq.md#zmq.Context) | None = None, root_topic: str = '')`

### Example Usage with `logging` module
```default
>>> import logging
>>> handler = PUBHandler('tcp://127.0.0.1:12345')
>>> handler.root_topic = 'foo'
>>> logger = logging.getLogger('foobar')
>>> logger.setLevel(logging.DEBUG)
>>> logger.addHandler(handler)
```

### Example Usage with `dictConfig`
```default
>>> from logging.config import dictConfig
>>> socket = Context.instance().socket(PUB)
>>> socket.connect('tcp://127.0.0.1:12345')
>>> dictConfig({
>>>     'version': 1,
>>>     'handlers': {
>>>         'zmq': {
>>>             'class': 'zmq.log.handlers.PUBHandler',
>>>             'level': logging.DEBUG,
>>>             'root_topic': 'foo',
>>>             'interface_or_socket': socket
>>>         }
>>>     },
>>>     'root': {
>>>         'level': 'DEBUG',
>>>         'handlers': ['zmq'],
>>>     }
>>> })
```

### Methods

#### `acquire()`
Acquire the I/O thread lock.

#### `addFilter(filter)`
Add the specified filter to this handler.

#### `close()`
Tidy up any resources used by the handler. This version removes the handler from an internal map of handlers, `_handlers`, which is used for handler lookup by name. Subclasses should ensure that this gets called from overridden close() methods.

#### `createLock()`
Acquire a thread lock for serializing access to the underlying I/O.

#### `emit(record)`
Emit a log message on my socket.

#### `filter(record)`
Determine if a record is loggable by consulting all the filters. The default is to allow the record to be logged; any filter can veto this and the record is then dropped. Returns a zero value if a record is to be dropped, else non-zero.

*Versionchanged*: Changed in version 3.2: Allow filters to be just callables.

#### `flush()`
Ensure all logging output has been flushed. This version does nothing and is intended to be implemented by subclasses.

#### `format(record)`
Format a record.

#### `get_name()`

#### `handle(record)`
Conditionally emit the specified logging record. Emission depends on filters which may have been added to the handler. Wrap the actual emission of the record with acquisition/release of the I/O thread lock. Returns whether the filter passed the record for emission.

#### `handleError(record)`
Handle errors which occur during an emit() call. This method should be called from handlers when an exception is encountered during an emit() call. If raiseExceptions is false, exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors. You could, however, replace this with a custom handler if you wish. The record which was being processed is passed in to this method.

#### `release()`
Release the I/O thread lock.

#### `removeFilter(filter)`
Remove the specified filter from this handler.

#### `setFormatter(fmt, level=0)`
Set the Formatter for this handler. If no level is provided, the same format is used for all levels. This will overwrite all selective formatters set in the object constructor.

#### `setLevel(level)`
Set the logging level of this handler. `level` must be an int or a str.

### Properties

#### `ctx *: [Context](zmq.md#zmq.Context)`

#### `name`

#### `root_topic *: str`
```

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

### Build and Upload Binary Distributions (OS X)

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

Builds and uploads eggs and wheels for PyZMQ on OS X, ensuring bundled ZeroMQ.

```bash
for fmt in egg wheel; do
    python setupegg.py bdist_$fmt upload --zmq=bundled
done
```

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

### pyzmq_version()

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

Get the PyZMQ library version.

```APIDOC
## pyzmq_version()

### Description
Get the PyZMQ library version.

### Function Signature
`zmq.pyzmq_version()`

### Returns
string: The PyZMQ library version.
```

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

### zmq_version()

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

Get the ZeroMQ library version.

```APIDOC
## zmq_version()

### Description
Get the ZeroMQ library version.

### Function Signature
`zmq.zmq_version()`

### Returns
string: The ZeroMQ library version.
```

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

### Download and Build pyzmq Wheel

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

Downloads the pyzmq source, extracts it, and then uses cross-python to build a wheel for the target architecture. This assumes dependencies like libzmq and libsodium are already built and available.

```bash
ARG PYZMQ_VERSION=26.0.0b2
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*
```

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

### Log Watcher Help

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

View the available options for the log watcher command-line utility by passing the --help parameter.

```bash
python -m zmq.log --help
```

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

### get

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

Retrieves the value of a specified socket option.

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

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

### Parameters
* **option** (int) - The option to get. Available values will 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.
```

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

### pyzmq_version_info()

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

Get the PyZMQ library version information.

```APIDOC
## pyzmq_version_info()

### Description
Get the PyZMQ library version information.

### Function Signature
`zmq.pyzmq_version_info()`

### Returns
tuple: A tuple containing the major, minor, and patch version numbers.
```

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

### zmq_version_info()

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

Get the ZeroMQ library version information.

```APIDOC
## zmq_version_info()

### Description
Get the ZeroMQ library version information.

### Function Signature
`zmq.zmq_version_info()`

### Returns
tuple: A tuple containing the major, minor, and patch version numbers.
```

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

### getsockopt_string

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

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

```APIDOC
## getsockopt_string

### Description
Get the value of a socket option as a unicode string.

### Parameters
* **option** (int) - The option to retrieve.
* **encoding** (str) - The encoding to use for the returned string. Defaults to 'utf-8'.

### Returns
**optval** - The value of the option as a unicode string.

### Return type
str
```

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

### strerror()

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

Get the string representation of a ZeroMQ error code.

```APIDOC
## strerror(error_code)

### Description
Get the string representation of a ZeroMQ error code.

### Parameters
#### Path Parameters
- **error_code** (int) - Required - The ZeroMQ error code.

### Returns
string: The string representation of the error code.
```

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

### Build PyZMQ with Custom Library Arguments

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

Set environment variables to customize the build, including specifying the libzmq prefix and custom arguments for libsodium configuration.

```bash
export ZMQ_PREFIX=bundled
export PYZMQ_LIBZMQ_VERSION=4.3.4
export PYZMQ_LIBSODIUM_CONFIGURE_ARGS=--disable-pie --minimal

python3 -m build .
```

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

### curve_public()

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

Get the public key for a CURVE key pair.

```APIDOC
## curve_public(secret_key)

### Description
Get the public key for a CURVE key pair.

### Parameters
#### Path Parameters
- **secret_key** (bytes) - Required - The secret key.

### Returns
bytes: The public key.
```

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

### Typing with zmq.Context and zmq.Socket

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

Demonstrates how to use zmq.Context and zmq.Socket with type annotations, including handling generic types and excluding async subclasses.

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

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

### zmq.device

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

Deprecated function for starting a ZeroMQ proxy. Use `zmq.proxy` instead.

```APIDOC
### zmq.device(device_type: [DeviceType](#zmq.DeviceType), frontend: [Socket](#zmq.Socket), backend: [Socket](#zmq.Socket))

Deprecated alias for zmq.proxy

#### Deprecated
Deprecated since version libzmq-3.2.

#### Deprecated
Deprecated since version 13.0.

```

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

### Build Dependencies for Crossenv

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

Installs necessary build tools within the crossenv environment for pyzmq compilation.

```bash
RUN . ${CROSS_PREFIX}/bin/activate \
 && build-pip install build pyproject_metadata scikit-build-core pathspec cython
```

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

### Getting Default Socket Options

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

Retrieves the default socket options for new sockets created by this context.

```python
default_sndhwm = ctx.getsockopt(zmq.SNDHWM)
```

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

### PUBHandler Initialization with Existing Socket

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

Initializes a PUBHandler using an already created and bound ZeroMQ PUB socket. This is an alternative to providing a socket address.

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

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

### Specify Bundled Library Download URLs

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

Provide full URLs to download specific versions of libsodium and libzmq for bundling. This is useful for testing unreleased versions.

```bash
-DPYZMQ_LIBZMQ_URL="https://github.com/zeromq/libzmq/releases/download/v4.3.5/zeromq-4.3.5.tar.gz"
-DPYZMQ_LIBSODIUM_URL="https://download.libsodium.org/libsodium/releases/libsodium-1.0.20.tar.gz"
```

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

### zmq.get_includes

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

Returns a list of directories to include for linking against pyzmq with cython.

```APIDOC
## zmq.get_includes()

### Description
Return a list of directories to include for linking against pyzmq with cython.
```

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

### Getting a Context Option

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

Retrieves the value of a specific context option. Available options depend on the libzmq version.

```python
io_threads = ctx.get(zmq.IO_THREADS)
```

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

### Configure PyZMQ Log Handler

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

Set up the ZMQ log handler by importing PUBHandler, creating an instance with a ZMQ address, and adding it to the root logger.

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

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

### TopicLogger Critical Example

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

Logs a message with CRITICAL severity and a specified topic. Use exc_info=True to include exception information.

```python
logger.critical("Houston, we have a %s", "major disaster", exc_info=True)
```

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

### TopicLogger Error Example

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

Logs a message with ERROR severity and a specified topic. Use exc_info=True to include exception information.

```python
logger.error("Houston, we have a %s", "major problem", exc_info=True)
```

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

### Device with Specified Socket Types

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

Initializes a Device with specific ZeroMQ socket types for frontend and backend. Sockets are created within the device's thread.

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

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

### Build Bundled libsodium with MSBuild on Windows

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

Build a static release of libsodium for x64 using MSBuild on Windows.

```bat
msbuild /m /v:n /p:Configuration=StaticRelease /pPlatform=x64 builds/msvc/vs2022/libsodium.sln
```

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

### Socket Options as Attributes

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

Set and get socket options using attribute access for convenience. This feature was added in version 2.1.9.

```python
s = ctx.socket(zmq.DEALER)
s.identity = b"dealer"
s.hwm = 10
s.events
# 0
s.fd
# 16
```

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

### Build libzmq as an Extension

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

Instruct PyZMQ to build libzmq as a Python extension by setting the ZMQ_PREFIX environment variable to 'bundled'. This is an alternative to linking against a system-installed libzmq.

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

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

### Subscribe to Topics with ZMQ SUB Socket

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

Demonstrates how to set up a ZMQ SUB socket to subscribe to specific topics, including the empty string for all messages.

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

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

### zmq.devices.monitored_queue

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

Starts a monitored queue device. This device is similar to zmq.proxy but offers additional features for handling ROUTER sockets and message prefixes.

```APIDOC
## zmq.devices.monitored_queue

### Description
Start a monitored queue device. A monitored queue is very similar to the zmq.proxy device (monitored queue came first).
Differences from zmq.proxy:
- monitored_queue supports both in and out being ROUTER sockets (via swapping IDENTITY prefixes).
- monitor messages are prefixed, making in and out messages distinguishable.

### Parameters
* **in_socket** (*zmq.Socket*) - One of the sockets to the Queue. Its messages will be prefixed with ‘in’.
* **out_socket** (*zmq.Socket*) - One of the sockets to the Queue. Its messages will be prefixed with ‘out’. The only difference between in/out socket is this prefix.
* **mon_socket** (*zmq.Socket*) - This socket sends out every message received by each of the others with an in/out prefix specifying which one it was.
* **in_prefix** (*bytes*) - Prefix added to broadcast messages from in_socket. Defaults to b'in'.
* **out_prefix** (*bytes*) - Prefix added to broadcast messages from out_socket. Defaults to b'out'.
```

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

### PUBHandler Initialization with Socket Address

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

Initializes a PUBHandler by providing a socket address to bind to. This is a convenient way to set up the handler without manually creating and binding a socket.

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

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

### Received Multipart Message Format

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

The expected format of a received multipart message from the PUB/SUB logging setup, showing the topic and log message.

```text
[b"myprogram.INFO", b"hello there"]
```

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

### Getting a Global Context Instance

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

Retrieves a singleton instance of zmq.Context, useful for single-process applications. Creates a new instance in subprocesses after forking.

```python
context = zmq.Context.instance()
```

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

### ContextOption Enum

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

Options for configuring ZeroMQ contexts.

```APIDOC
## ContextOption Enum

### Description
Options for configuring ZeroMQ contexts.

### Options
- `ContextOption.IO_THREADS`: Number of I/O threads.
- `ContextOption.MAX_SOCKETS`: Maximum number of sockets.
- `ContextOption.SOCKET_LIMIT`: Socket limit.
- `ContextOption.THREAD_SCHED_POLICY`: Thread scheduling policy.
- `ContextOption.MAX_MSGSZ`: Maximum message size.
- `ContextOption.MSG_T_SIZE`: Size of message type.
- `ContextOption.THREAD_AFFINITY_CPU_ADD`: Add CPU to thread affinity.
- `ContextOption.THREAD_AFFINITY_CPU_REMOVE`: Remove CPU from thread affinity.
- `ContextOption.THREAD_NAME_PREFIX`: Prefix for thread names.
```

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

### Setting Default Search Paths for CMake

Source: https://github.com/zeromq/pyzmq/blob/main/CMakeLists.txt

Configures CMake's search path for libraries by checking common installation prefixes and environment variables.

```cmake
foreach(prefix $ENV{PREFIX} "/opt/homebrew" "/opt/local" "/usr/local" "/usr")
  if (IS_DIRECTORY "${prefix}")
    list(APPEND CMAKE_PREFIX_PATH "${prefix}")
  endif()
endforeach()
```

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

### Run PyZMQ Test Suite

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

Execute the PyZMQ test suite using pytest. This command should be run after installing the test requirements and building the extension.

```bash
pytest
```