Pynng

0.9.0 · active · verified Fri Apr 17

Pynng is a Python binding for the nng (nanomsg-next-generation) C library, providing lightweight, high-performance messaging patterns for network communication. It supports both synchronous and asynchronous (asyncio) operations, making it suitable for a wide range of network applications. The current version is 0.9.0, and it generally follows a moderate release cadence, with updates often introducing significant features or improvements.

Common errors

```
error: command 'gcc' failed with exit status 1
```
cause The `pynng` installation failed to compile the underlying `nng` C library because a C compiler or necessary development headers were not found on the system.

fix Install a C compiler and development headers. For Linux (Debian/Ubuntu): `sudo apt-get install build-essential`. For macOS: `xcode-select --install`. For Windows, consider using WSL or Visual Studio Build Tools.
```
AttributeError: 'Socket' object has no attribute 'recv'
```
cause You are likely trying to call the synchronous `recv()` method on an asynchronous socket (or vice-versa), or you've made a typo. The method names for async operations are prefixed with 'a' (e.g., `arecv`).

fix If using `asyncio`, use `await sock.arecv()` and `await sock.asend()`. If explicitly using synchronous operations (less common in modern `pynng` code), ensure you are calling the non-`a` prefixed methods (`sock.recv()`, `sock.send()`).
```
pynng.exceptions.NNGException: nng_dial failed: connection refused
```
cause The client attempted to connect to a server address, but no server was listening on that address and port, or a firewall is blocking the connection.

fix Ensure your server process is running and actively listening on the specified address and port before the client attempts to dial. Check firewall rules if the server is on a different machine or network.

Warnings

gotcha Pynng requires the nng C library. If it's not pre-installed on your system, `pip install pynng` will attempt to download and compile it from source. This requires a C compiler (e.g., GCC or Clang) and development headers to be available on your system.
Fix: Ensure you have a C compiler and development headers installed. On Debian/Ubuntu: `sudo apt-get install build-essential`. On Fedora: `sudo dnf groupinstall "Development Tools"`. On macOS: Install Xcode Command Line Tools (`xcode-select --install`).
breaking Asyncio support was a major addition in pynng >= 0.8.0. Code written for older synchronous versions might need significant refactoring to take advantage of `asyncio` and `await`/`async` syntax (e.g., `sock.arecv()` instead of `sock.recv()`).
Fix: For new applications, prefer `asyncio` methods (`asend`, `arecv`, `aconnect`, `aclose`). For existing sync code, ensure you're explicitly using `send`, `recv`, etc., and be mindful of blocking operations in an `asyncio` context.
gotcha Improper context management (introduced in 0.9.0) can lead to resource leaks or unexpected behavior, especially in complex applications or when dealing with multiple concurrency units.
Fix: Always use `with sock.open_context() as ctx:` for managing `nng` contexts, ensuring they are properly closed. Refer to the official `pynng` documentation for advanced context usage patterns.

Install

pip install pynng Install pynng

Imports

pynng
wrong:
```
import nng
```
correct:
```
import pynng
```
The library is imported under the 'pynng' namespace, not directly 'nng'.
Rep0, Req0
```
from pynng import Rep0, Req0
```
Common socket types are directly available from the top-level pynng module.

Quickstart

This quickstart demonstrates a basic asynchronous request-reply (REQ/REP) pattern using pynng. It sets up a minimal server that listens for messages and replies, and a client that sends messages and receives replies. Both are run concurrently using asyncio.

import pynng
import asyncio

async def main():
    addr = "tcp://127.0.0.1:5555"

    async def server():
        """Simple Request-Reply server."""
        with pynng.Rep0() as rep_sock:
            rep_sock.listen(addr)
            print("Server: Listening...")
            # Receive and immediately reply, then close after 2 messages
            for _ in range(2):
                msg = await rep_sock.arecv()
                print(f"Server: Received '{msg.decode()}'")
                await rep_sock.asend(b"PONG")
            print("Server: Done.")

    async def client():
        """Simple Request-Reply client."""
        await asyncio.sleep(0.1) # Give server a moment to start
        with pynng.Req0() as req_sock:
            req_sock.dial(addr)
            print("Client: Dialed.")
            for i in range(2):
                await req_sock.asend(f"PING {i}".encode())
                reply = await req_sock.arecv()
                print(f"Client: Received '{reply.decode()}'")
            print("Client: Done.")

    await asyncio.gather(server(), client())

if __name__ == "__main__":
    # This example demonstrates async usage, which is common in modern pynng applications.
    asyncio.run(main())

view raw JSON →