bitspark-bitwire 0.1.0__tar.gz → 0.2.0__tar.gz

{bitspark_bitwire-0.1.0/src/bitspark_bitwire.egg-info → bitspark_bitwire-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bitspark-bitwire
-Version: 0.1.0
+Version: 0.2.0
 Summary: The shared relative-path Wire contract for Python
 Author: Bitspark
 License-Expression: Apache-2.0
@@ -26,7 +26,7 @@ The package contains typed declarations and supporting values; endpoint runtimes
 carriers, codecs and routing helpers belong to implementations.
 
 ```python
-from bitwire import Message, Receiver, ReturnAddress, Wire
+from bitwire import Endpoint, Message, Receiver, ReturnAddress, Wire
 
 
 def call(endpoint: Wire, replies: Wire) -> None:
@@ -39,18 +39,22 @@ def call(endpoint: Wire, replies: Wire) -> None:
     )
 
 
-def listen(endpoint: Wire):
+def listen(endpoint: Endpoint):
     def receive(path, message):
         print(path, message.frame)
 
-    return endpoint.receive([], Receiver(namespace=True, message=receive))
+    return endpoint.receive(Receiver(message=receive))
 ```
 
-`Wire` is a structural `Protocol`; implementations do not need to inherit from
-it. `send` accepts or refuses synchronously; the implementation schedules delivery.
-Receivers may return an awaitable. `receive` returns an idempotent detach function.
+`Wire` is a send-only structural `Protocol`; implementations do not need to inherit
+from it. `send` accepts or refuses synchronously; the implementation schedules
+delivery. `Endpoint` extends it with `receive(receiver)` and `close`, keeping
+attachment and closure authority separate from send access. One receive attachment
+is allowed at a time; duplicates are refused. Receivers may return an awaitable.
+`receive` returns an idempotent detach function that cannot remove a replacement.
+Path matching belongs to routing compositions, not to these interfaces.
 Paths are sequences of opaque Unicode-scalar strings and retain empty segments.
-Receiver paths are relative to the Wire on which they registered.
+Receiver paths are relative to the attached endpoint.
 
 `ReturnAddress` uses object identity, including when its Wire cannot be compared
 or hashed. Preserve this object during routing. The return address is local

{bitspark_bitwire-0.1.0 → bitspark_bitwire-0.2.0}/README.md

@@ -6,7 +6,7 @@ The package contains typed declarations and supporting values; endpoint runtimes
 carriers, codecs and routing helpers belong to implementations.
 
 ```python
-from bitwire import Message, Receiver, ReturnAddress, Wire
+from bitwire import Endpoint, Message, Receiver, ReturnAddress, Wire
 
 
 def call(endpoint: Wire, replies: Wire) -> None:
@@ -19,18 +19,22 @@ def call(endpoint: Wire, replies: Wire) -> None:
     )
 
 
-def listen(endpoint: Wire):
+def listen(endpoint: Endpoint):
     def receive(path, message):
         print(path, message.frame)
 
-    return endpoint.receive([], Receiver(namespace=True, message=receive))
+    return endpoint.receive(Receiver(message=receive))
 ```
 
-`Wire` is a structural `Protocol`; implementations do not need to inherit from
-it. `send` accepts or refuses synchronously; the implementation schedules delivery.
-Receivers may return an awaitable. `receive` returns an idempotent detach function.
+`Wire` is a send-only structural `Protocol`; implementations do not need to inherit
+from it. `send` accepts or refuses synchronously; the implementation schedules
+delivery. `Endpoint` extends it with `receive(receiver)` and `close`, keeping
+attachment and closure authority separate from send access. One receive attachment
+is allowed at a time; duplicates are refused. Receivers may return an awaitable.
+`receive` returns an idempotent detach function that cannot remove a replacement.
+Path matching belongs to routing compositions, not to these interfaces.
 Paths are sequences of opaque Unicode-scalar strings and retain empty segments.
-Receiver paths are relative to the Wire on which they registered.
+Receiver paths are relative to the attached endpoint.
 
 `ReturnAddress` uses object identity, including when its Wire cannot be compared
 or hashed. Preserve this object during routing. The return address is local

{bitspark_bitwire-0.1.0 → bitspark_bitwire-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bitspark-bitwire"
-version = "0.1.0"
+version = "0.2.0"
 description = "The shared relative-path Wire contract for Python"
 readme = "README.md"
 requires-python = ">=3.11"

{bitspark_bitwire-0.1.0 → bitspark_bitwire-0.2.0/src/bitspark_bitwire.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bitspark-bitwire
-Version: 0.1.0
+Version: 0.2.0
 Summary: The shared relative-path Wire contract for Python
 Author: Bitspark
 License-Expression: Apache-2.0
@@ -26,7 +26,7 @@ The package contains typed declarations and supporting values; endpoint runtimes
 carriers, codecs and routing helpers belong to implementations.
 
 ```python
-from bitwire import Message, Receiver, ReturnAddress, Wire
+from bitwire import Endpoint, Message, Receiver, ReturnAddress, Wire
 
 
 def call(endpoint: Wire, replies: Wire) -> None:
@@ -39,18 +39,22 @@ def call(endpoint: Wire, replies: Wire) -> None:
     )
 
 
-def listen(endpoint: Wire):
+def listen(endpoint: Endpoint):
     def receive(path, message):
         print(path, message.frame)
 
-    return endpoint.receive([], Receiver(namespace=True, message=receive))
+    return endpoint.receive(Receiver(message=receive))
 ```
 
-`Wire` is a structural `Protocol`; implementations do not need to inherit from
-it. `send` accepts or refuses synchronously; the implementation schedules delivery.
-Receivers may return an awaitable. `receive` returns an idempotent detach function.
+`Wire` is a send-only structural `Protocol`; implementations do not need to inherit
+from it. `send` accepts or refuses synchronously; the implementation schedules
+delivery. `Endpoint` extends it with `receive(receiver)` and `close`, keeping
+attachment and closure authority separate from send access. One receive attachment
+is allowed at a time; duplicates are refused. Receivers may return an awaitable.
+`receive` returns an idempotent detach function that cannot remove a replacement.
+Path matching belongs to routing compositions, not to these interfaces.
 Paths are sequences of opaque Unicode-scalar strings and retain empty segments.
-Receiver paths are relative to the Wire on which they registered.
+Receiver paths are relative to the attached endpoint.
 
 `ReturnAddress` uses object identity, including when its Wire cannot be compared
 or hashed. Preserve this object during routing. The return address is local

{bitspark_bitwire-0.1.0 → bitspark_bitwire-0.2.0}/src/bitwire/__init__.py

@@ -25,6 +25,7 @@ __all__ = [
     "Message",
     "Receiver",
     "Wire",
+    "Endpoint",
 ]
 
 # Opaque Unicode-scalar segments: [] != [""] != ["a/b"] != ["a", "b"].
@@ -111,30 +112,39 @@ class Message:
 
 @dataclass(frozen=True)
 class Receiver:
-    """Callbacks receive paths relative to the Wire on which they registered.
+    """Callbacks receive every path relative to their attached endpoint.
 
-    Exact routes win, then the longest namespace segment prefix wins. A receiver
-    may be synchronous or awaitable; endpoint implementations own dispatch.
+    A receiver may be synchronous or awaitable; endpoints own dispatch.
     """
 
-    namespace: bool = False
     message: Callable[[Path, Message], None | Awaitable[None]] | None = None
     closed: Callable[[int, str], None] | None = None
 
 
 @runtime_checkable
 class Wire(Protocol):
-    """Access to an origin with synchronous admission and asynchronous dispatch.
+    """Send-only access with synchronous admission and asynchronous dispatch.
 
     send returns on acceptance or raises on refusal, without running destination
-    application code on the sender's stack. receive refuses duplicate paths and
-    returns an idempotent detach. A root owns dispatch, bounds and closure; a
-    selected view shares that closure, while a mount owns only its registrations
-    and routing. Structural protocol matching alone does not prove these laws.
+    application code on the sender's stack. It grants no receiving or closure
+    authority. Structural protocol matching alone does not prove these laws.
     """
 
     def send(self, path: Path, message: Message) -> None: ...
 
-    def receive(self, path: Path, receiver: Receiver) -> Callable[[], None]: ...
+
+@runtime_checkable
+class Endpoint(Wire, Protocol):
+    """Owning endpoint access with one receive attachment and endpoint closure.
+
+    receive refuses a second active attachment or a closed endpoint and returns
+    an idempotent detach. A stale detach cannot remove a later attachment. Callbacks receive the complete
+    message and its relative path; routing policy belongs above this boundary.
+    Detach preserves captured return access and does not close the endpoint.
+    Closing notifies the active receiver once; detached receivers are not notified.
+    Closing twice has no additional effect and does not release live bindings.
+    """
+
+    def receive(self, receiver: Receiver) -> Callable[[], None]: ...
 
     def close(self, code: int = 1000, reason: str = "") -> None: ...

{bitspark_bitwire-0.1.0 → bitspark_bitwire-0.2.0}/tests/test_consumer.py

@@ -7,7 +7,7 @@ import inspect
 import unittest
 from collections.abc import Callable
 
-from bitwire import Message, Path, Receiver, ReturnAddress, Wire
+from bitwire import Endpoint, Message, Path, Receiver, ReturnAddress, Wire
 
 
 class RecordingEndpoint:
@@ -15,7 +15,8 @@ class RecordingEndpoint:
 
     def __init__(self) -> None:
         self.sent: list[tuple[tuple[str, ...], Message]] = []
-        self.receivers: dict[tuple[str, ...], Receiver] = {}
+        self.receiver: Receiver | None = None
+        self.attachment: object | None = None
         self.ending: tuple[int, str] | None = None
 
     def __eq__(self, other: object) -> bool:
@@ -24,17 +25,31 @@ class RecordingEndpoint:
     def send(self, path: Path, message: Message) -> None:
         self.sent.append((tuple(path), message))
 
-    def receive(self, path: Path, receiver: Receiver) -> Callable[[], None]:
-        key = tuple(path)
-        self.receivers[key] = receiver
+    def receive(self, receiver: Receiver) -> Callable[[], None]:
+        if self.ending is not None:
+            raise RuntimeError("endpoint closed")
+        if self.receiver is not None:
+            raise RuntimeError("receiver already attached")
+        token = object()
+        self.receiver = receiver
+        self.attachment = token
 
         def detach() -> None:
-            self.receivers.pop(key, None)
+            if self.attachment is token:
+                self.receiver = None
+                self.attachment = None
 
         return detach
 
     def close(self, code: int = 1000, reason: str = "") -> None:
+        if self.ending is not None:
+            return
         self.ending = (code, reason)
+        receiver = self.receiver
+        self.receiver = None
+        self.attachment = None
+        if receiver is not None and receiver.closed is not None:
+            receiver.closed(code, reason)
 
 
 class ConsumerTests(unittest.TestCase):
@@ -72,14 +87,13 @@ class ConsumerTests(unittest.TestCase):
             await asyncio.sleep(0)
             observed.append((tuple(path), message))
 
-        receiver = Receiver(namespace=True, message=delivered)
-        detach = endpoint.receive(["reply"], receiver)
+        receiver = Receiver(message=delivered)
+        detach = endpoint.receive(receiver)
         request = Message({"version": 1, "kind": "event", "data": None})
 
         async def dispatch() -> None:
-            registered = endpoint.receivers[("reply",)]
-            self.assertTrue(registered.namespace)
-            assert registered.message is not None
+            registered = endpoint.receiver
+            assert registered is not None and registered.message is not None
             result = registered.message(["reply", ""], request)
             if inspect.isawaitable(result):
                 await result
@@ -88,9 +102,47 @@ class ConsumerTests(unittest.TestCase):
         self.assertEqual(observed, [(("reply", ""), request)])
         detach()
         detach()
-        self.assertEqual(endpoint.receivers, {})
+        self.assertIsNone(endpoint.receiver)
         self.assertIsNone(endpoint.ending)
 
+    def test_attachment_ownership_and_stale_detach(self) -> None:
+        endpoint: Endpoint = RecordingEndpoint()
+        first = Receiver()
+        detach = endpoint.receive(first)
+        with self.assertRaises(RuntimeError):
+            endpoint.receive(first)
+        detach()
+        second = Receiver()
+        second_detach = endpoint.receive(second)
+        detach()
+        assert isinstance(endpoint, RecordingEndpoint)
+        self.assertIs(endpoint.receiver, second)
+        second_detach()
+        self.assertIsNone(endpoint.receiver)
+
+    def test_close_notifies_only_active_attachment_once(self) -> None:
+        endpoint = RecordingEndpoint()
+        endings: list[tuple[int, str]] = []
+        detached: list[tuple[int, str]] = []
+        endpoint.receive(Receiver(closed=lambda c, r: detached.append((c, r))))()
+        endpoint.receive(Receiver(closed=lambda c, r: endings.append((c, r))))
+        endpoint.close(1000, "done")
+        endpoint.close(1001, "again")
+        self.assertEqual(endings, [(1000, "done")])
+        self.assertEqual(detached, [])
+        with self.assertRaises(RuntimeError):
+            endpoint.receive(Receiver())
+
+    def test_send_only_wire_requires_no_endpoint_control(self) -> None:
+        class Access:
+            def send(self, path: Path, message: Message) -> None:
+                pass
+
+        access: Wire = Access()
+        self.assertIsInstance(access, Wire)
+        self.assertNotIsInstance(access, Endpoint)
+        self.assertIs(ReturnAddress(access).wire, access)
+
     def test_closed_callback_is_independent_from_message_callback(self) -> None:
         endings: list[tuple[int, str]] = []
         receiver = Receiver(closed=lambda code, reason: endings.append((code, reason)))
@@ -98,7 +150,7 @@ class ConsumerTests(unittest.TestCase):
         receiver.closed(1000, "complete")
         self.assertEqual(endings, [(1000, "complete")])
         self.assertIsNone(receiver.message)
-        self.assertFalse(receiver.namespace)
+
 
 
 if __name__ == "__main__":

{bitspark_bitwire-0.1.0 → bitspark_bitwire-0.2.0}/tests/typecheck.py

@@ -5,6 +5,7 @@ from typing import assert_type
 from bitwire import (
     CancelFrame,
     ErrorFrame,
+    Endpoint,
     EventFrame,
     Message,
     Path,
@@ -18,7 +19,7 @@ from bitwire import (
 )
 
 
-def consume(wire: Wire, frame: ProfileFrame) -> None:
+def consume(wire: Wire, endpoint: Endpoint, frame: ProfileFrame) -> None:
     address = ReturnAddress(wire)
     wire.send(["scope", ""], Message(frame, address))
     assert_type(address.wire, Wire)
@@ -30,7 +31,9 @@ def consume(wire: Wire, frame: ProfileFrame) -> None:
     async def delivered(path: Path, message: Message) -> None:
         assert_type(message.return_address, ReturnAddress | None)
 
-    wire.receive([], Receiver(namespace=True, message=delivered))()
+    endpoint.receive(Receiver(message=delivered))()
+    wire.receive(Receiver())  # type: ignore[attr-defined]
+    wire.close()  # type: ignore[attr-defined]
     wire.send([42], Message(frame))  # type: ignore[list-item]