pynng

pynng is designed to be used in various execution environments. It provides first-class support for:

• Synchronous usage (standard blocking calls).
• asyncio (asynchronous I/O).
• Trio (asynchronous I/O).

The pynng.Socket class is the base class for all sockets in pynng. You should never instantiate pynng.Socket directly. Instead, you must instantiate one of the specific protocol subclasses provided by the library. Each subclass implements a specific communication pattern (e.g., Request/Reply, Publish/Subscribe).

import pynng

# Correct: Use a protocol subclass
with pynng.Req0() as sock:
    pass

# Incorrect: Do not instantiate Socket directly
# sock = pynng.Socket()

pynng translates all NNG error codes into Python exceptions. The base class for all exceptions in this library is NNGException, which inherits from the built-in Exception. You can catch all pynng-related errors by catching NNGException.

from pynng.exceptions import NNGException

try:
    # pynng operation
    pass
except NNGException:
    # handles any error originating from NNG
    pass

You can use TLS on top of TCP by specifying a URL scheme starting with tls+. This is configured via the address string passed to listen() or dial().

Valid TLS address examples:

• tls+tcp:127.0.0.1:1313: Listen on TCP port 1313 on localhost.
• tls+tcp4:127.0.0.1:1313: Explicitly request IPv4 for TCP port 1313 on localhost.
• tls+tcp6://[::1]:4433: Explicitly request IPv6 for IPv6 localhost on port 4433.

You can install pynng using pip. On Windows, MacOS, and Linux, the standard installation command is usually sufficient.

Note for 32-bit Linux and macOS: Binary distributions are not available for these platforms. You must have CMake installed to build from source.

To build directly from the GitHub repository, use:

git clone https://github.com/codypiersall/pynng
cd pynng
pip3 install -e .

pip3 install pynng

pynng is installable with pip on Linux, Windows, and macOS. It requires Python 3.6 or newer.

pip3 install pynng

The survey pattern allows a Surveyor0 socket to send a message and give all connected Respondent0 sockets a chance to respond.

Key details:

• Surveyor0 sockets use the survey_time attribute to define how long a survey is valid (in milliseconds).
• Respondent0 sockets are the counterparts that receive the survey and chime in.

Example usage (conceptual):

# Surveyor0 setup
with Surveyor0(survey_time=1000) as surveyor:
    # ... survey logic ...

# Respondent0 setup
with Respondent0(listen='tcp://127.0.0.1:12345') as respondent:
    # ... respond to surveys ...

# See snippets/surveyor_sync.py in the repository for a full implementation example

Options can be set or retrieved on various pynng objects (Socket, Dialer, Listener, Pipe, or Context). The library provides specialized internal handlers for different data types to ensure correct C-level type mapping.

When setting integer-based options (like int, size, or ms), the library accepts floats as long as they are exactly equal to their integer representation (e.g., 1.0 is accepted as 1).

Common option types supported:

• Boolean: Use for flags.
• Integer/Size/MS: Use for counts, sizes, or durations (milliseconds).
• String: Use for text-based configuration.
• Sockaddr: Use for address-related configurations.
• Pointer (TLS): Specifically used for passing pynng.tls.TLSConfig objects.

pynng uses an internal AIOHelper class to bridge NNG's asynchronous I/O with Python's asynchronous frameworks. It detects the running event loop using sniffio and applies specific machinery to ensure compatibility:

• asyncio: Uses asyncio_helper to create futures and reschedule the event loop via loop.call_soon_threadsafe when NNG callbacks trigger.
• trio: Uses trio_helper to manage Trio's low-level task rescheduling and cancellation mechanics, ensuring that Trio cancellations are correctly propagated to NNG via nng_aio_cancel.