pymizu 0.0.1.dev0__tar.gz

pymizu-0.0.1.dev0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,46 @@
+# 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/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pymizu"
+version = "0.0.1.dev0"
+description = "Single-producer single-consumer channels"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "pymizu authors" }]
+keywords = ["channel", "concurrency", "spsc"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/shikokuchuo/mizu-py"
+Issues = "https://github.com/shikokuchuo/mizu-py/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+packages = ["pymizu"]
+
+[tool.setuptools.package-data]
+pymizu = ["py.typed"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 79
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

pymizu-0.0.1.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pymizu-0.0.1.dev0/src/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-0.0.1.dev0/src/pymizu/py.typed

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

pymizu-0.0.1.dev0/src/pymizu.egg-info/PKG-INFO

@@ -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/src/pymizu.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/pymizu/__init__.py
+src/pymizu/py.typed
+src/pymizu.egg-info/PKG-INFO
+src/pymizu.egg-info/SOURCES.txt
+src/pymizu.egg-info/dependency_links.txt
+src/pymizu.egg-info/top_level.txt
+tests/test_channel.py

pymizu-0.0.1.dev0/src/pymizu.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pymizu-0.0.1.dev0/src/pymizu.egg-info/top_level.txt

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

pymizu-0.0.1.dev0/tests/test_channel.py

@@ -0,0 +1,185 @@
+import gc
+import math
+import threading
+import time
+
+import pytest
+
+from pymizu import (
+    CLOSED,
+    FULL,
+    TIMEOUT,
+    InprocChannel,
+    Sentinel,
+    inproc_channel,
+    is_sentinel,
+)
+
+
+def test_values_round_trip_in_fifo_order():
+    ch = inproc_channel(2)
+    assert isinstance(ch, InprocChannel)
+    ch.send("a")
+    ch.send(42)
+    assert ch.recv() == "a"
+    assert ch.recv() == 42
+
+
+def test_none_is_a_legal_payload():
+    ch = inproc_channel(1)
+    ch.send(None)
+    assert ch.recv() is None
+
+
+def test_the_ring_wraps():
+    ch = inproc_channel(2)
+    for i in range(5):
+        ch.send(i)
+        assert ch.recv() == i
+    ch.send(1)
+    ch.send(2)
+    assert ch.send(3) is FULL
+    assert ch.recv() == 1
+    ch.send(3)
+    assert ch.recv() == 2
+    assert ch.recv() == 3
+
+
+def test_a_large_ring_preserves_order_and_integrity():
+    n = 10000
+    ch = inproc_channel(n)
+    for i in range(n):
+        ch.send(i)
+    assert ch.send(n) is FULL
+    assert [ch.recv() for _ in range(n)] == list(range(n))
+
+
+def test_the_buffer_survives_garbage_collection():
+    ch = inproc_channel(2)
+    ch.send("a")
+    gc.collect()
+    assert ch.recv() == "a"
+
+
+def test_send_on_a_full_channel_returns_full_without_waiting():
+    ch = inproc_channel(1)
+    assert ch.send("a") is True
+    assert ch.send("b") is FULL
+
+
+def test_recv_on_an_empty_channel_returns_timeout():
+    ch = inproc_channel(1)
+    assert ch.recv(timeout=0) is TIMEOUT
+    assert ch.recv(timeout=0.01) is TIMEOUT
+
+
+def test_the_timeout_is_respected():
+    ch = inproc_channel(1)
+    start = time.monotonic()
+    assert ch.recv(timeout=0.05) is TIMEOUT
+    assert time.monotonic() - start >= 0.04
+
+
+def test_close_drains_then_reports_closed():
+    ch = inproc_channel(2)
+    ch.send("a")
+    assert ch.close() is True
+    assert ch.recv() == "a"
+    assert ch.recv() is CLOSED
+    assert ch.send("b") is CLOSED
+    assert ch.close() is True
+
+
+def test_is_sentinel_is_an_identity_test():
+    assert is_sentinel(FULL)
+    assert is_sentinel(TIMEOUT)
+    assert is_sentinel(CLOSED)
+    assert not is_sentinel("a")
+    assert not is_sentinel(None)
+    assert not is_sentinel(Sentinel("TIMEOUT"))
+
+
+def test_a_forwarded_sentinel_arrives_as_an_ordinary_copy():
+    ch = inproc_channel(1)
+    ch.send(TIMEOUT)
+    x = ch.recv()
+    assert isinstance(x, Sentinel)
+    assert repr(x) == repr(TIMEOUT)
+    assert not is_sentinel(x)
+
+
+def test_a_sentinel_payload_drains_before_the_closed_sentinel():
+    ch = inproc_channel(1)
+    ch.send(FULL)
+    ch.close()
+    x = ch.recv()
+    assert isinstance(x, Sentinel)
+    assert not is_sentinel(x)
+    assert ch.recv() is CLOSED
+
+
+def test_a_channel_repr_shows_state_and_occupancy():
+    ch = inproc_channel(2)
+    assert repr(ch) == "<pymizu.InprocChannel: open, 0/2 buffered>"
+    ch.send("a")
+    assert repr(ch) == "<pymizu.InprocChannel: open, 1/2 buffered>"
+    ch.close()
+    assert repr(ch) == "<pymizu.InprocChannel: closed, 1/2 buffered>"
+
+
+def test_sentinels_repr_as_their_name():
+    assert repr(FULL) == "<pymizu.FULL>"
+    assert repr(TIMEOUT) == "<pymizu.TIMEOUT>"
+    assert repr(CLOSED) == "<pymizu.CLOSED>"
+
+
+def test_misuse_is_an_error():
+    with pytest.raises(ValueError, match="capacity"):
+        inproc_channel(0)
+    with pytest.raises(TypeError, match="capacity"):
+        inproc_channel(1.5)
+    with pytest.raises(TypeError, match="capacity"):
+        inproc_channel(True)
+    ch = inproc_channel(1)
+    with pytest.raises(ValueError, match="timeout"):
+        ch.recv(timeout=-1)
+    with pytest.raises(ValueError, match="timeout"):
+        ch.recv(timeout=math.nan)
+    with pytest.raises(TypeError, match="timeout"):
+        ch.recv(timeout="1")
+
+
+def test_recv_waits_indefinitely_by_default():
+    ch = inproc_channel(1)
+    threading.Timer(0.05, ch.send, args=("a",)).start()
+    assert ch.recv() == "a"
+
+
+def test_an_infinite_timeout_waits_indefinitely():
+    ch = inproc_channel(1)
+    threading.Timer(0.05, ch.send, args=("a",)).start()
+    assert ch.recv(timeout=math.inf) == "a"
+
+
+def test_close_wakes_a_blocked_recv():
+    ch = inproc_channel(1)
+    threading.Timer(0.05, ch.close).start()
+    assert ch.recv() is CLOSED
+
+
+def test_producer_and_consumer_across_threads():
+    n = 1000
+    ch = inproc_channel(8)
+    out = []
+
+    def consume():
+        for _ in range(n):
+            out.append(ch.recv())
+
+    consumer = threading.Thread(target=consume, daemon=True)
+    consumer.start()
+    for i in range(n):
+        while ch.send(i) is FULL:
+            time.sleep(0)
+    consumer.join(timeout=10)
+    assert out == list(range(n))