pymizu 0.0.1.dev0__py3-none-any.whl

pymizu/__init__.py

@@ -0,0 +1,186 @@
+"""Single-producer single-consumer channels for Python.
+
+A bounded ring buffer with optional timeouts on receives and sentinel
+return values for full, timeout, and closed states. The transport is
+in-process: both ends of a channel live in the calling Python process,
+which suits the channel to prototyping producer and consumer designs
+and to testing channel-based logic.
+
+This interface is experimental and may change in a future release.
+"""
+
+from __future__ import annotations
+
+import copy
+import math
+import threading
+import time
+from collections import deque
+from typing import Any
+
+__version__ = "0.0.1.dev0"
+
+__all__ = [
+    "CLOSED",
+    "FULL",
+    "TIMEOUT",
+    "InprocChannel",
+    "Sentinel",
+    "__version__",
+    "inproc_channel",
+    "is_sentinel",
+]
+
+
+class Sentinel:
+    """A channel terminal state as an ordinary value, not an exception.
+
+    The singletons FULL, TIMEOUT, and CLOSED are interned: identity is
+    the test, and is_sentinel() is provenance — True only for the
+    exact objects the channel verbs return. A sentinel forwarded as a
+    payload arrives as an ordinary copy.
+    """
+
+    __slots__ = ("_name",)
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+
+    def __repr__(self) -> str:
+        return f"<pymizu.{self._name}>"
+
+    def __copy__(self) -> Sentinel:
+        return Sentinel(self._name)
+
+
+FULL = Sentinel("FULL")
+"""The buffer is at capacity (InprocChannel.send())."""
+
+TIMEOUT = Sentinel("TIMEOUT")
+"""No value arrived within timeout (InprocChannel.recv())."""
+
+CLOSED = Sentinel("CLOSED")
+"""The channel is closed, and drained for InprocChannel.recv()."""
+
+_SENTINELS = (FULL, TIMEOUT, CLOSED)
+
+
+def is_sentinel(x: Any) -> bool:
+    """Test for a pymizu sentinel.
+
+    Identity comparison against the interned sentinel singletons —
+    True only for the exact objects the channel verbs themselves
+    return. A sentinel forwarded over a channel arrives as an ordinary
+    copy and fails this test, so code that relays untrusted values can
+    distinguish its own terminal states from look-alike payloads.
+    """
+    return any(x is s for s in _SENTINELS)
+
+
+class InprocChannel:
+    """A single-producer single-consumer channel: a bounded ring buffer.
+
+    Sends and receives are O(1). Both ends of the channel live in the
+    calling process; the buffer is lock-guarded, so a producer thread
+    and a consumer thread may exchange values without an external
+    lock.
+    """
+
+    __slots__ = ("_buf", "_capacity", "_closed", "_cond")
+
+    def __init__(self, capacity: int) -> None:
+        if isinstance(capacity, bool) or not isinstance(capacity, int):
+            raise TypeError("pymizu: capacity must be a positive integer")
+        if capacity < 1:
+            raise ValueError("pymizu: capacity must be a positive integer")
+        self._buf: deque[Any] = deque()
+        self._capacity = capacity
+        self._closed = False
+        self._cond = threading.Condition()
+
+    def __repr__(self) -> str:
+        with self._cond:
+            state = "closed" if self._closed else "open"
+            return (
+                f"<pymizu.InprocChannel: {state}, "
+                f"{len(self._buf)}/{self._capacity} buffered>"
+            )
+
+    def send(self, x: Any) -> bool | Sentinel:
+        """Append x to the buffer.
+
+        Sends never block: a send on a full channel returns FULL
+        immediately, and a send on a closed channel returns CLOSED.
+        Returns True on success.
+        """
+        with self._cond:
+            if self._closed:
+                return CLOSED
+            if len(self._buf) == self._capacity:
+                return FULL
+            self._buf.append(x)
+            self._cond.notify()
+            return True
+
+    def recv(self, timeout: float | None = None) -> Any:
+        """Remove and return the oldest buffered value.
+
+        Waits up to timeout seconds for one to arrive: None (the
+        default) and math.inf wait indefinitely, and 0 polls. Returns
+        TIMEOUT when the wait expires. A closed channel drains its
+        buffered values before recv() reports CLOSED.
+
+        The wait is on a monotonic clock: system clock adjustments do
+        not affect it.
+        """
+        deadline = _recv_deadline(timeout)
+        with self._cond:
+            while not self._buf:
+                if self._closed:
+                    return CLOSED
+                if deadline is None:
+                    self._cond.wait()
+                    continue
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return TIMEOUT
+                self._cond.wait(remaining)
+            x = self._buf.popleft()
+        if is_sentinel(x):
+            # A forwarded sentinel crosses as an ordinary copy, so a
+            # returned singleton always tags a terminal state.
+            return copy.copy(x)
+        return x
+
+    def close(self) -> bool:
+        """Orderly shutdown.
+
+        Values buffered before the close remain receivable; further
+        sends return CLOSED, and a receive on a drained channel
+        returns the same. Closing an already-closed channel is a
+        no-op. Returns True.
+        """
+        with self._cond:
+            self._closed = True
+            self._cond.notify_all()
+            return True
+
+
+def _recv_deadline(timeout: float | None) -> float | None:
+    if timeout is None or timeout == math.inf:
+        return None
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+        raise TypeError("pymizu: timeout must be a non-negative number")
+    if math.isnan(timeout) or timeout < 0:
+        raise ValueError("pymizu: timeout must be a non-negative number")
+    return time.monotonic() + timeout
+
+
+def inproc_channel(capacity: int) -> InprocChannel:
+    """Create a single-producer single-consumer channel.
+
+    capacity is a positive integer: the number of values the channel
+    buffers before send() returns the FULL sentinel. Returns an
+    InprocChannel.
+    """
+    return InprocChannel(capacity)

pymizu/py.typed

@@ -0,0 +1 @@
+# PEP 561 marker: this package ships inline type information.

pymizu-0.0.1.dev0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: pymizu
+Version: 0.0.1.dev0
+Summary: Single-producer single-consumer channels
+Author: pymizu authors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shikokuchuo/mizu-py
+Project-URL: Issues, https://github.com/shikokuchuo/mizu-py/issues
+Keywords: channel,concurrency,spsc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pymizu
+
+Single-producer single-consumer channels for Python: a bounded ring
+buffer with optional timeouts on receives and sentinel return values
+for full, timeout, and closed states. The transport is in-process.
+
+## Installation
+
+```sh
+pip install pymizu
+```
+
+## Usage
+
+```python
+import pymizu
+
+ch = pymizu.inproc_channel(2)
+
+ch.send("a")
+ch.send(42)
+ch.send("b")        # full: returns the pymizu.FULL sentinel
+
+ch.recv()
+# 'a'
+ch.recv()
+# 42
+ch.recv(timeout=0)  # empty: do not wait
+# <pymizu.TIMEOUT>
+
+ch.close()
+```
+
+`timeout` is in seconds on a monotonic clock: `None` (the default) and
+`math.inf` wait indefinitely, and `0` polls. The buffer is
+lock-guarded, so a producer thread and a consumer thread may exchange
+values without an external lock.
+
+Terminal states surface as sentinel singletons, not exceptions:
+`pymizu.FULL`, `pymizu.TIMEOUT`, and `pymizu.CLOSED`.
+`pymizu.is_sentinel(x)` is an identity test for use where payloads are
+untrusted.
+
+## License
+
+MIT

pymizu-0.0.1.dev0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pymizu/__init__.py,sha256=n7C7JZdDbA8Ezs_P4pJ1LIrm2Cjl7ioKzcAt1QzyymQ,6045
+pymizu/py.typed,sha256=UYkntRy6-so-avkIET2nEnwoqE8LDrAyAGoImVTRPoc,62
+pymizu-0.0.1.dev0.dist-info/licenses/LICENSE,sha256=xRD4WE0rFyYSQ12E7feo0kE59W53K3aLmy-mzfXRmoo,1073
+pymizu-0.0.1.dev0.dist-info/METADATA,sha256=lneaTshOR8lDssFP_r7cqk2pGfhGuKdiZpXxVLXR0As,1637
+pymizu-0.0.1.dev0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pymizu-0.0.1.dev0.dist-info/top_level.txt,sha256=IY3CQRUHe0BxB3vwcAzZPYJliioOVgsMLLcCQW1Tj8Q,7
+pymizu-0.0.1.dev0.dist-info/RECORD,,

pymizu-0.0.1.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pymizu-0.0.1.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 pymizu authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pymizu-0.0.1.dev0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pymizu