loop-node

loop-node is the low-level runtime and wire protocol shared by Loop and loop-sdk. Most integrations should use loop-sdk directly; use loop-node when building a lower-level Node API or integration layer.

Installation

pip install loop-node

Published wheels support CPython 3.10–3.14 on Linux x86_64 (glibc 2.28+). They contain compiled implementation modules and type stubs; installation does not require a compiler.

Minimal example

import time

from loop_node import (
    EmptyConfig,
    FieldContract,
    LifecycleState,
    Node,
    NodeConnectionConfig,
    PayloadContract,
    ValueKind,
)

VALUE = PayloadContract(fields={"value": FieldContract(kind=ValueKind.SCALAR)})

node = Node(config_type=EmptyConfig)
output = node.declare_stream_output("value", payload_contract=VALUE)
node.start(
    node_id="example_node",
    connection=NodeConnectionConfig(loop_endpoint="tcp/127.0.0.1:7448"),
)

try:
    while node.is_running:
        node.process_control()
        if node.status.lifecycle is LifecycleState.ACTIVE:
            output.publish(timestamp_ns=time.time_ns(), payload={"value": 1.0})
        time.sleep(0.1)
finally:
    if node.status.lifecycle is not LifecycleState.FINALIZED:
        node.shutdown()
    node.close()

A Node declares its Config and Ports before connecting. Loop supplies the validated Config, Port bindings, and lifecycle operations. Call process_control() regularly to handle lifecycle requests from Loop. Use the Node lifecycle state to decide when your application should exchange Graph data. In most cases, only exchange data while the Node is ACTIVE.

Lifecycle

All Nodes use IDLE → Configure → CONFIGURED → Start → ACTIVE. Configure validates Config and calls optional on_configure(config) before Port binding. Start takes only bindings and calls optional on_start(). Stop and ResetFault return to IDLE; each restart requires Configure again. Configure may update existing payload contracts. The Orchestrator validates the resulting graph before starting Nodes. Port names and kinds stay fixed.

Describe returns the Config schema and current Port contracts for inspection. Loop uses Configure results for payload compatibility checks; contracts read through Describe are not treated as finalized for a run.

Port transport policy

Declare a transport policy on each Port, independently of the Node connection:

Policy Binding behavior
auto (default) Image contracts use SHM when every peer passes an actual SHM round trip; otherwise use ordinary Zenoh network transmission. Contracts without images use network transmission.
zenoh_network Require ordinary Zenoh transmission, including for local peers.
zenoh_shared_memory Require SHM for all payload types. An inaccessible peer or conflicting policy rejects binding before application Start. 
from loop_node import TransportMode

# Optional policy; omitting transport is equivalent to AUTO.
image_output = node.declare_stream_output(
    "image", payload_contract=IMAGE_CONTRACT,
    transport=TransportMode.AUTO,
)
policy = node.declare_request_client(
    "action", request=OBSERVATION_CONTRACT, response=ACTION_CONTRACT,
    request_transport=TransportMode.AUTO,
    response_transport=TransportMode.ZENOH_NETWORK,
)

The examples assume the payload contracts have been declared. Both endpoints advertise policies and supported transports in their Port contracts. An explicit policy constrains an auto peer; contradictory policies fail. Request and reply are negotiated independently, so an observation with images can use SHM while its small action response uses the network path. TCP/UDP endpoint selection is still Zenoh session configuration, independent of these Port policies.

One provider Port currently uses one common mode for all its receivers. For image fanout, every receiver must pass the SHM probe; a remote receiver makes an automatic provider use network transmission for all receivers. SHM-only Ports instead reject an incompatible connection. Probes use dedicated control endpoints and never invoke a user handler or robot action.

A binding keeps its selected mode until it is released. Partial Node restarts retain the graph's common mode while any Node remains started. Stop all Nodes before renegotiating, changing contracts, or reconnecting peers. Configuration changes that preserve Port contracts and graph connections are allowed. Selected modes and reasons are logged when bindings are created. Probes check memory accessibility; later allocation exhaustion or transport loss is still an error, not a reason to resend a request or silently change mode.

Cell Config bindings now contain only from; they do not store transfer modes. The appended collect_cell_config_2_0_0_auto_transport migration removes old binding profile fields from all saved revisions while preserving Node Config and other graph content. The low-level Graph Config has a shared_memory_pool_size_bytes limit (default 64 MiB per sending Port).

This protocol requires loop-node 0.3.x on Loop and external Nodes. Control protocol version 2 rejects older Node registrations. Existing publish, poll, request, Payload, ImageValue, and step APIs keep the same application data interface. Use the matching SDK update when importing through loop-sdk.

Image framing and SHM lifetime

Loop uses Zenoh 1.10.1. Image bytes are outside the Protobuf body for both network and SHM transmission. Protobuf metadata in the attachment describes one contiguous binary payload by field name, offset, and length. When a payload contains images, its tensor and audio fields share that buffer. Network payloads without images use ordinary Protobuf. Explicit SHM packs every payload, including scalar-only and empty payloads (one padding byte for an empty binary buffer).

Zenoh's implicit transport SHM optimization is disabled in Loop sessions so zenoh_network remains network transmission. Loop's auto policy negotiates explicit SHM instead. SHM support remains enabled. Physical transport changes are rejected by graph input and RPC bindings. Passive recorder previews are observers: they can also decode ordinary copies delivered outside the graph's negotiated SHM peers.

Each SHM sending Port owns a bounded pool. The limit must cover in-flight data, values retained by receivers, and allocation overhead. The receiver validates buffer ranges, layout, and sizes. Image/audio values retain their Zenoh payload and remain readable after the binding or session closes. Retaining request images does not keep their Query open. Releasing values allows the sender to reclaim allocations; retaining them can exhaust its pool. Request timeouts and client closure do not interrupt a handler already running on the server.

Zenoh Python 1.10.1 does not expose received SHM through the Python buffer protocol. Packed ranges share a lazy Python snapshot, and tensor decoding materializes it to preserve TensorValue.data as a read-only memoryview. This is not end-to-end zero-copy NumPy access.

On Linux, Zenoh locks mapped SHM into memory. Each process needs a sufficient RLIMIT_MEMLOCK limit for the pools it creates or maps, and containers need enough /dev/shm capacity for all participating processes. Wheel tests configure Docker with --shm-size=256m --ulimit=memlock=268435456:268435456 for their multi-process image requests and replies. Size these limits for the pools used by your application; a small limit can reject pool creation before any data is sent.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for chanyoungkim-configinc from gravatar.com chanyoungkim-configinc

Requires

Python >=3.10

Provides Extra

numpy

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

loop_node-0.3.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

loop_node-0.3.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

loop_node-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

loop_node-0.3.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

loop_node-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

loop_node-0.3.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

loop_node-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.0 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

loop_node-0.3.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (943.4 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

loop_node-0.3.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (978.1 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

loop_node-0.3.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (919.3 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

File details

Details for the file loop_node-0.3.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a05a3ca1c6ecf13b7f06373f90fa1e22bc967171ede940e303060d5823dceeae
MD5 36fda10689375431f272d8420cca428f
BLAKE2b-256 2d2be33791ac81812ede63594bac3c13d80bf9da68c6497e17e110bb45ae523c

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file loop_node-0.3.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 f97eeacabfb8a2f329f02afe77403dd5af637b65893b362772e2edb28e9bf711
MD5 679bdc1c262298d97c9a89195db3d89d
BLAKE2b-256 e1e99e93d5b64a9ce7d49c512cc527d3ed3a36da17ef2b1af9eafb1a06e7b0e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file loop_node-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5e5e56a1f618f6ee5efa7f7cfefe5f620b62d097e1ae5a45daa836be97dfde8b
MD5 450448695896f320a6715e556c299d5f
BLAKE2b-256 4c3d59f6bcb6a017827cd7bdf1a26a8e3866e04a04257ace82bcf96915a1d3cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file loop_node-0.3.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 533f0ddda7daa23278fa80d6db3c71a124905357c853d6124af6086d293d0b1d
MD5 546e39cc14a23c109dd2076028e1ddf3
BLAKE2b-256 f887aa8a4362e7a28756c76a5a85bf4ce01dea48a5809b75e5db8705c777393d

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file loop_node-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d79a9615a9dfe41ecbe0ef64a3137f04e479115483d6bbcba3ddfc6f70e0ae28
MD5 8c5a60b95e93ff98dac3c9989b6671a5
BLAKE2b-256 8bbd238f38f2fdb9bc221e7f34e9e4afbbb982bc8eab1c54b22af155b863fd23

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file loop_node-0.3.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 cba027966f12dc11584cff6a572ec2a76e29b1239eb6fa79304d4c6fb3966255
MD5 e698a8cc5456df513957e6184401fe0e
BLAKE2b-256 cdf7ad665fdb493ac475ed88dd5652ede22180b53efb4255c62c247c557bdb45

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file loop_node-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 90c1f119763530a388b17380c2143697999f10e3e8dae4f0fb37b2138d230d2b
MD5 b51e287fffc9af0954db0a824b6080e4
BLAKE2b-256 8b95f512d778296f9bac2347f1c8a28e36f54078a93b466c32215631305ad4fc

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file loop_node-0.3.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 0fddc598ae77a051474892b760d909fdf8b40d5e461b1d691304de39dd9388b6
MD5 e4e0b39df231b990236940f21f6253af
BLAKE2b-256 2fd85e01d72d7aeed3a19006ffe2a12e4bb749f1181e6dd20d29d6e63de45b78

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file loop_node-0.3.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b80a39b9751c14b986d0eff42d9a656376a229fb3df721cc25647055eb8918b1
MD5 28e5bc70952557a1fbc30af124c7906f
BLAKE2b-256 fec58c2d60494154959a0fb480f00ad127461c120e9da23de8523d066a7a6dab

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file loop_node-0.3.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for loop_node-0.3.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 92b003ef18a6d28df9b71585fb6a842ec500ffc7fd51f27329ccdb887cc07165
MD5 f1d45e83dbf9d8423a9b0c0bfa700bbd
BLAKE2b-256 6abf4dcfa4cbfbf9efa01d8639d7b334e838f6ee249937cba9e95657c35490b6

See more details on using hashes here.

Provenance

The following attestation bundles were made for loop_node-0.3.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl:

Publisher: loop-node-publish.yml on configinc/loop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.0 This release

10 files

0.2.0

10 files

0.1.0

10 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page