Python API reference

Send Python bytes and buffer objects through the shared Rust engine. Use context managers to keep endpoint lifetimes explicit.

Python package source ↗ · Binding implementation ↗

Install from source

The Python package is not yet published on PyPI. Requires Python 3.9 or later, Git, Rust, and a native linker. Run in an activated virtual environment:

python -m pip install "git+https://github.com/cloudtoid/interprocess.git@native-v3.0.1#subdirectory=src/python"

Send and receive

from cloudtoid_interprocess import Publisher, Subscriber

with Subscriber("example", 65536) as subscriber:
    with Publisher("example", 65536) as publisher:
        if not publisher.try_send(b"hello"):
            raise RuntimeError("Queue is full or recovering")
        message = subscriber.receive(timeout=1.0)
        if message is None:
            raise TimeoutError("No message arrived")
        print(message.decode("utf-8"))

Publisher

Publisher(name, capacity, path=None)

Creates or joins the queue. name is a string, capacity is integer message-buffer bytes, and path is an optional filesystem path for Unix storage. The default is the OS temporary directory; Windows ignores path.

try_send(data) -> bool

Accepts bytes and objects implementing the buffer protocol, including bytearray and memoryview. Non-bytes inputs are snapshotted before sending. Returns False when full or recovering, True on commit; other failures raise.

try_send_batch(messages) -> int

Pass a list of bytes-like messages. Returns the committed prefix length. A short count can mean full capacity, recovery, or a mid-batch error. Retry only the unsent suffix. Errors before any commit are raised immediately; the batch is not transactional.

close() -> None

Releases the endpoint. Repeated close is safe. Publisher supports with via __enter__ and __exit__; leaving the block closes it without suppressing exceptions.

Subscriber

Subscriber(name, capacity, path=None)

Creates or joins the queue with the same configuration rules as Publisher.

try_receive() -> bytes | None

Consumes one ready message and returns bytes. None means no message is ready. b"" is a valid empty message, so test message is not None rather than truthiness.

receive(timeout=None) -> bytes | None

Blocks until delivery or timeout. Timeout is a finite nonnegative number of seconds; None waits indefinitely and zero attempts once. Returns None on timeout. Negative, infinite, and NaN timeout values raise ValueError.

close() -> None

Releases the subscriber. Repeated close is safe. Subscriber also supports with. A concurrent close waits for the current bounded native wait before releasing the handle.

Exceptions

InterprocessError

Base for queue-specific exceptions below, not for every possible API failure.

CapacityMismatchError

Existing capacity differs; also a ValueError.

PublisherLimitError

No publisher slot is available; also a RuntimeError.

CorruptQueueError

Shared state is invalid; also a RuntimeError.

ValueError

Invalid configuration, invalid timeout, or a closed endpoint.

OverflowError

Counter exhaustion or an integer outside a native argument's range.

OSError

Operating-system failure.

TypeError

Invalid argument type or unsupported buffer object.

Waiting, signals, and lifetime

Receive releases the GIL while waiting and checks Python signals between native waits of at most 100 ms, subject to scheduling. A received message is returned rather than discarded to report a later signal. There is no native asyncio API; use a worker thread with bounded timeouts for orderly shutdown. Cancelling an asyncio wrapper does not stop its already-running blocking call.

No public receive-into method is exposed. Close endpoints with context managers and keep their lifetimes overlapping across processes; see transient lifetime.