NNG for Python (pynng 0.9.0 over NNG 1.11.0) — feature parity

The parity document of weida-nng-py, the Python binding of the weida-nng library. Its reference implementation is pynng, because that is what a Python program that speaks the Scalability Protocols uses today; the protocol-level parity against NNG itself is nng.md and is not repeated here — this document cites its sections instead. One question per row: what does a Python caller who knows pynng get, and what does that caller not get.

1. What a row means

Three verdicts and no others:

• present — implemented, with the module or the test that proves it;
• refused — the call exists and fails at configuration time with a reason the code gives;
• absent — not implemented, with what is missing named.

"Partial" is not a verdict (0013 §4.7 clause 6). Where this binding's shape differs from pynng's the row says so and §9 states why.

Two C releases, and every row says which one it was measured against. This library is now measured against two different builds of the NNG C implementation, which is worth more than either alone:

The 1.11.0 figure is not assumed: pynng.ffi.string(pynng.lib.nng_version()) answers 1.11.0 in this worktree's virtualenv today, and pynng reports 0.9.0 (§11 names the command). The pynng version is not pinned anywhere: develop.sh installs it as uv pip install --python .venv pynng, pyproject.toml declares no dependency on it, and tests/test_interop.py::test_the_c_library_is_the_one_this_test_claims asserts only that the C library is an NNG 1.x. A later develop.sh run may therefore measure a different 1.x, and the test will still pass — which is the honest bound on every claim in §8.

Everything else was measured against: CPython 3.13 with the abi3 wheel built from CPython 3.9, PyO3 0.29 (abi3-py39, workspace Cargo.toml), Linux x86-64. Rows about the Rust side cite crates/nng/weida-nng/src/; rows about SP itself cite nng.md and, through it, ../research/nanomsg-nng.md.

2. Socket and protocol types

Eleven protocol classes in pynng, eleven here — src/sockets.rs, one python_socket! invocation each, and eleven more in src/sync.rs for the synchronous surface (§9.5).

3. Transports

The binding exposes what the library parses; a URL is bounded by NNG_MAXADDRLEN = 128 before anything else happens (tests/test_options.py::test_a_url_past_nng_maxaddrlen_is_refused_before_it_is_parsed). The pynng column was measured on this machine against its bundled NNG 1.11.0 by attempting a listen on each scheme (§11).

4. Mechanisms and authentication

SP has no authentication of its own, and that is a property of the protocol rather than a gap in either implementation: no mechanism negotiation, no credential frame, no signature (nng.md §4). What remains is what the transport can prove.

5. Options

Two surfaces, answering two questions, and both are the library's own table rather than a retyped copy.

• weida_nng.OPTIONS and weida_nng.option(name) are all 50 rows of nng_options(5) as weida-nng's optiontable.rs answers them — 33 honoured, 17 refused (§11 gives the commands). Each row is an NngOption with name, scope, honoured, note and refusal; a refused row always carries the reason and an honoured one never does, which a test walks over the whole table (tests/test_options.py::test_the_option_table_answers_for_every_name_it_carries). A name NNG does not have answers None.
• weida_nng.SocketOptions(**kwargs) is what a socket is opened with: fifteen keyword arguments (src/options.rs:49-66), frozen, validated at construction.

The refusal vocabulary a Python caller sees is the library's errno classes, not a string:

Twelve of the fifteen keywords are NNG options under NNG's own semantics — recv_max_size (NNG_OPT_RECVMAXSZ), send_depth (SENDBUF), recv_depth (RECVBUF), send_timeout (SENDTIMEO), recv_timeout (RECVTIMEO), reconnect_min/reconnect_max (RECONNMINT/RECONNMAXT), max_ttl (MAXTTL), resend_time (REQ_RESENDTIME), survey_time (SURVEYOR_SURVEYTIME), sub_prefer_new (SUB_PREFNEW), subscribe (SUB_SUBSCRIBE). The other three — max_pipes, max_addresses, handshake_timeout — are bounds NNG has no option for (§9.8).

Differences from pynng's option surface:

6. Observability

7. Devices and helpers

A note on the manifest rather than on the API: weida-sp is a declared dependency of crates/nng/weida-nng-py "for the raw socket's constructor" (Cargo.toml:33-36), and grep -rn 'weida_sp' crates/nng/weida-nng-py/src finds no use of it — consistent with the two absences above.

8. Interop evidence

crates/nng/weida-nng-py/tests/test_interop.py — six tests, against pynng over the NNG C library it bundles, which is 1.11.0 in this worktree (§1). Where pynng is absent every test skips with its install command in the skip message. Every pynng call is blocking and runs in a worker thread through asyncio.to_thread, because a blocking C call on the event-loop thread would deadlock against the coroutine it waits for.

REQ/REP is exercised in both roles and on both sides of the bind, which is B-137's acceptance clause; PUB/SUB, PUSH/PULL and SURVEYOR/RESPONDENT are exercised in one role each. Nothing disagreed in the recorded run: B-137 merged with all of them passing and NIGHTLOG.md 2026-09-12T07:35Z records the run; B-138 added the synchronous surface and its entry records 51 Python tests. This document counted the suite from the source rather than re-running it (§11).

What the interop does not cover, named rather than implied:

• PAIR v0, PAIR v1 and BUS against the C library. They are covered only between two sockets of this binding (tests/test_sockets.py). A hop-count or PAIR-v0 header disagreement with NNG would not be caught here.
• ipc:// and inproc:// against the C library. All six tests use loopback TCP. inproc:// cannot cross implementations by construction; ipc:// could and is not tested.
• The synchronous surface against pynng. tests/test_sync.py::test_the_two_surfaces_talk_to_each_other crosses weida_nng.sync with weida_nng, which proves one implementation underneath, not the C library's agreement.
• Any cost measurement. There is no roundtrip_cost.py for this binding, so unlike zmq-py.md §8 this document quotes no microseconds.

9. Deliberate deviations, and bounds NNG does not have

1. Two coroutines may use one socket at once — unlike this workspace's ZeroMQ binding (zmq-py.md §9.1), and not a limitation here. A weida-nng socket's send and recv take &self and the socket is Sync, so a receive parked on an empty socket does not hold it against a send: tests/test_sockets.py::test_two_coroutines_may_use_one_socket_at_once. Where a protocol does need one transaction at a time it says so per context, with ESTATE, which is SP's own answer — tests/test_contexts.py::test_a_context_that_answers_out_of_turn_is_refused_and_its_neighbour_is_not.
2. Every call that can wait is a coroutine, including dial, listen and Context.shutdown. dial_nowait, send_nowait and recv_nowait are synchronous because they never wait. A cancelled task leaves the socket usable — test_a_cancelled_receive_leaves_the_socket_usable.
3. Seconds, not milliseconds, for every duration, with None where NNG writes NNG_DURATION_INFINITE (§5). pynng takes milliseconds as integers.
4. A payload is bytes, both ways, and a str is refused rather than encoded (§2).
5. The synchronous surface is a facade over a facade and implements nothing. weida_nng.sync is the same eleven protocols and the same three context classes over weida-nng's own blocking module, which the binding enables as a Cargo feature (Cargo.toml:32, B-138). No protocol behaviour exists twice, which is why the two surfaces cannot disagree and why a sync socket and an asyncio socket exchange a message in the suite (test_the_two_surfaces_talk_to_each_other). The GIL is released — py.detach around every blocking send, recv, dial, listen and shutdown (sync.rs:146, 190, 299, 311, 115) — so one thread parked in recv does not stop another (test_a_blocked_thread_does_not_hold_the_gil), and no asyncio loop exists in such a process (test_no_event_loop_is_running_while_this_suite_runs).
6. weida_nng.sync.Context is the owned constructor only. The asyncio Context has three (Context(), current(), sharing(other)) and six properties; the synchronous one has the default constructor, max_sockets, socket_count and shutdown (sync.rs:67-126). What is missing on the synchronous side: the ambient and shared reactors, and the closed/worker_threads/close_budget properties.
7. Failures are classes, not numbers — 23 exception classes under weida_nng.NngError, one per weida_nng::Error variant, each carrying errno and cause (errors.rs:40-64). The table cannot drift: the name list and the exhaustive match come from one macro, so a variant added to the library and not here is a compile error. pynng has 31 classes under pynng.NNGException; the nine it has that this does not are ENOMEM, EBUSY, ENOSPC, EEXIST, ECRYPTO, ENOARG, EAMBIGUOUS, EBADTYPE and EINTERNAL — conditions of the C implementation the Rust library has no variant for — and the one this has that pynng does not is ESYSERR.
8. Bounds NNG does not have, all inherited from the library, all settable, all readable from Python as module constants (§5): pipes per socket (max_pipes, 1024), addresses one name may resolve to (max_addresses, 8), sockets per context (max_sockets, 1023), queue depth (MAX_QUEUE_DEPTH, 8192), and the handshake timeout, which NNG has no option for at all. nng.md §9 lists them with their reasons.
9. Two defaults differ from NNG, both inherited and both settable back: NNG_OPT_RECVMAXSZ is 1 MiB where NNG's is unlimited, and a context's close budget is finite (1 s, DEFAULT_CLOSE_BUDGET) where nng_close waits for its own drain (nng.md §9).
10. shutdown reports rather than raises. await ctx.shutdown() answers how many sockets were still open when the budget ran out — a number to log or retry against, because a peer that will not go away is not that call's failure (context.rs:185-197).

10. The definition of done

B-137's and B-138's acceptance clauses, plus B-183's, each with its verdict.

11. Sources, and the commands behind every count

• Code: crates/nng/weida-nng-py/src/ — lib.rs, sockets.rs, contexts.rs, context.rs, options.rs, subscriptions.rs, values.rs, errors.rs, sync.rs — and crates/py/weida-py-core/src/. The library: crates/nng/weida-nng/src/ (optiontable.rs, options.rs, engine.rs, raw.rs).
• Tests: crates/nng/weida-nng-py/tests/ — test_sockets.py, test_options.py, test_contexts.py, test_sync.py, test_interop.py. Build and run: ./develop.sh (uv virtualenv, maturin develop, pytest), which also installs pynng.
• pynng's surface was read from the copy in this worktree's virtualenv: .venv/lib/python3.13/site-packages/pynng/ — nng.py, exceptions.py, tls.py, __init__.py.

Every count in this document, with the command that produces it:

• Decisions: 0014 §2 (one shared PyO3 foundation, asyncio first, the synchronous surface second and over the same code, the bytes boundary), 0013 §4.4 (options honoured or refused at configuration time, no second implementation in the binding) and §4.7 clause 6 (no "partial").
• The library's own parity table: nng.md — §2 protocols, §3 transports, §4 mechanisms, §5 the 50 option rows, §6 pipes and events, §7 raw mode and nng_device, §9 bounds. The protocol sheet it cites: ../research/nanomsg-nng.md.
• Backlog: B-137 (the asyncio surface), B-138 (the synchronous surface), B-183 (this document), in BACKLOG.md.

What this document could not check, stated rather than guessed:

1. The pynng version is unpinned. 0.9.0 over NNG 1.11.0 is what this worktree's virtualenv holds today; nothing in the repository fixes it, and the suite asserts only 1.x. Any §8 claim is a claim about that build.
2. The suite was not re-run for this document. The 43 test functions and 51 cases are counted from the source; the last recorded green run is B-138's, which reports 51.
3. Whether weida-sp in the binding's manifest is intended for a future raw-socket surface or is a leftover is not stated in the crate; §7 records only that nothing under src/ refers to it.
4. The ws://, wss:// and tls+tcp:// probes in §3 record that pynng's bundled build accepted a listen call, not that a handshake completes on them. Only udp://'s refusal is a completed negative.