borgee-plugin-sdk 0.1.2__py3-none-any.whl

borgee_plugin_sdk/testing/fake_transport.py

@@ -0,0 +1,125 @@
+"""Deterministic in-memory transport for SDK consumers' tests."""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+from ..errors import BorgeeError, NotOnlineError
+from ..models import ConnectionState, ConnectionStatus, DeliveryEvent
+
+
+@dataclass(frozen=True, slots=True)
+class RecordedAction:
+    operation: str
+    payload: dict[str, Any]
+
+
+class FakeDelivery:
+    def __init__(self, event: DeliveryEvent) -> None:
+        self.event = event
+        self.cursor = event.cursor
+        self.checkpointed = False
+        self.failed = False
+
+    async def checkpoint(self) -> None:
+        if self.failed:
+            raise BorgeeError("fake delivery was already failed", "bpp.delivery_resolved")
+        self.checkpointed = True
+
+    async def fail(self, error: BaseException | None = None) -> None:
+        if self.checkpointed:
+            raise BorgeeError("fake delivery was already checkpointed", "bpp.delivery_resolved")
+        self.failed = True
+
+
+class FakeTransport:
+    def __init__(self, *, agent_id: str = "agent-test") -> None:
+        self._agent_id = agent_id
+        self._state = ConnectionState(ConnectionStatus.CONNECTING)
+        self._connected = False
+        self.actions: list[RecordedAction] = []
+        self.task_frames: list[dict[str, Any]] = []
+        self._results: deque[Any] = deque()
+        self._delivery_queue: asyncio.Queue[FakeDelivery | None] = asyncio.Queue()
+        self._state_queue: asyncio.Queue[ConnectionState] = asyncio.Queue()
+
+    @property
+    def agent_id(self) -> str:
+        return self._agent_id
+
+    @property
+    def state(self) -> ConnectionState:
+        return self._state
+
+    def queue_result(self, value: Any) -> None:
+        self._results.append(value)
+
+    def queue_error(self, error: BaseException) -> None:
+        self._results.append(error)
+
+    async def emit(self, event: DeliveryEvent) -> FakeDelivery:
+        delivery = FakeDelivery(event)
+        await self._delivery_queue.put(delivery)
+        return delivery
+
+    async def connect(self) -> None:
+        self._connected = True
+        self._set_state(ConnectionState(ConnectionStatus.ONLINE))
+
+    async def close(self) -> None:
+        self._connected = False
+        self._set_state(ConnectionState(ConnectionStatus.CLOSED))
+        await self._delivery_queue.put(None)
+
+    async def perform(self, operation: str, payload: dict[str, Any]) -> Any:
+        if not self._connected:
+            raise NotOnlineError()
+        self.actions.append(RecordedAction(operation, payload))
+        if not self._results:
+            return None
+        result = self._results.popleft()
+        if isinstance(result, BaseException):
+            raise result
+        return result
+
+    async def report_task_started(self, task_id: str, channel_id: str, subject: str) -> None:
+        if not self._connected:
+            raise NotOnlineError()
+        self.task_frames.append(
+            {"type": "task_started", "task_id": task_id, "channel_id": channel_id, "subject": subject}
+        )
+
+    async def report_task_finished(self, task_id: str, channel_id: str, outcome: str, reason: str) -> None:
+        if not self._connected:
+            raise NotOnlineError()
+        self.task_frames.append(
+            {
+                "type": "task_finished",
+                "task_id": task_id,
+                "channel_id": channel_id,
+                "outcome": outcome,
+                "reason": reason,
+            }
+        )
+
+    async def deliveries(self) -> AsyncIterator[FakeDelivery]:
+        while True:
+            delivery = await self._delivery_queue.get()
+            if delivery is None:
+                return
+            yield delivery
+
+    async def state_changes(self) -> AsyncIterator[ConnectionState]:
+        while True:
+            state = await self._state_queue.get()
+            yield state
+            if state.status is ConnectionStatus.CLOSED:
+                return
+
+    def _set_state(self, state: ConnectionState) -> None:
+        self._state = state
+        self._state_queue.put_nowait(state)

borgee_plugin_sdk-0.1.2.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: borgee-plugin-sdk
+Version: 0.1.2
+Summary: Async Python SDK for Borgee plugin runtimes
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets==15.0.1
+Provides-Extra: test
+Requires-Dist: build==1.2.2.post1; extra == "test"
+Requires-Dist: mypy==1.17.0; extra == "test"
+Requires-Dist: PyYAML==6.0.2; extra == "test"
+Requires-Dist: pytest==9.0.3; extra == "test"
+Requires-Dist: pytest-asyncio==1.3.0; extra == "test"
+Requires-Dist: pytest-timeout==2.4.0; extra == "test"
+Requires-Dist: ruff==0.12.4; extra == "test"
+Requires-Dist: twine==6.1.0; extra == "test"
+Dynamic: license-file
+
+# Borgee Plugin SDK for Python
+
+`borgee-plugin-sdk` connects a Python runtime to Borgee over the Borgee Plugin
+Protocol (BPP). It supports Python 3.11 through 3.13 and pins
+`websockets==15.0.1` because the connection hardening depends on that exact
+client implementation.
+
+Build a wheel from this directory or install the source checkout for evaluation. The repository also provides a manual workflow for publishing to TestPyPI and PyPI.
+
+```bash
+python -m pip install .
+```
+
+```python
+import asyncio
+
+from borgee_plugin_sdk import BorgeePluginOptions, ReplayMode, create_borgee_plugin
+
+
+async def main() -> None:
+    client = create_borgee_plugin(
+        BorgeePluginOptions(
+            base_url="https://chat.example.com",
+            api_key="bgr_example",
+            replay_mode=ReplayMode.LATEST_N,
+        )
+    )
+    async with client:
+        async for delivery in client.deliveries():
+            print(delivery.event)
+            await delivery.checkpoint()
+
+
+asyncio.run(main())
+```
+
+Every inbound message or replay summary is a `Delivery`. The iterator has one
+consumer, and it will not advance until the consumer calls `checkpoint()` or
+`fail()`. Actions fail while the connection is resuming; replay consumption
+continues until the client becomes online.
+
+For local development, insecure transport is restricted to loopback origins and
+requires `allow_insecure_loopback=True`. API keys are sent only in the WebSocket
+`Authorization` header. Redirects are rejected.
+
+This package is licensed under the MIT License.

borgee_plugin_sdk-0.1.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+borgee_plugin_sdk/__init__.py,sha256=mkHNldPhkI_cqjcewoIDNBcsJEVaXagz4bC0KKLsQuQ,1738
+borgee_plugin_sdk/_connection.py,sha256=9e5sWDqBKjxA_ep7r3BZi5kHNNhwZvdgAQNIRUn2KqA,71893
+borgee_plugin_sdk/client.py,sha256=86i6gnT2VpngHWG_pyqSj-L0O5oOeVAiAYTArFPj0kA,14379
+borgee_plugin_sdk/cursor.py,sha256=pupAO9Ibz1HW8j3z8Pfby9IYqxEjgyHl_ORh1LP74lc,8315
+borgee_plugin_sdk/errors.py,sha256=fwdyeQ74DPTborJ6Xsrw6lEGuAvQl_0TEfA7_QVCN0s,1926
+borgee_plugin_sdk/models.py,sha256=9re3KR5GYOjuRXTtSrjgRNTDdr5TeEmBqD316pXGNTE,9073
+borgee_plugin_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+borgee_plugin_sdk/_wire/__init__.py,sha256=0a0KwUmK_dVKAavxkjLc7X8vPzjEve3VfBWLdWdOCg4,163
+borgee_plugin_sdk/_wire/frames_generated.py,sha256=RTjg0uvhoeyczpLqzg1JPRToGf-uYxmQyMlmUeTz8PM,6475
+borgee_plugin_sdk/testing/__init__.py,sha256=qr6O4dxujS9VC5AGxlYwhGnhb_jSWGGPHC5AbWR1MrY,534
+borgee_plugin_sdk/testing/fake_transport.py,sha256=xwPsmgGqkURmeVJaJdIpPzly2BRVtiZgaZJbklIZ4fk,4178
+borgee_plugin_sdk-0.1.2.dist-info/licenses/LICENSE,sha256=Zw1UDBR9zRXe3VzNzoW0GSdU-AgMJMPdDkTFHXL_Weg,1076
+borgee_plugin_sdk-0.1.2.dist-info/METADATA,sha256=bqU4KmVrA3aS7UeNrodT7DzqNmfgO8_wx43YKKA20CQ,2498
+borgee_plugin_sdk-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+borgee_plugin_sdk-0.1.2.dist-info/top_level.txt,sha256=cfqq-Jl2KXSJ2YeP0E1QlcdewQHrEc9dDTx0CZ4s-dc,18
+borgee_plugin_sdk-0.1.2.dist-info/RECORD,,

borgee_plugin_sdk-0.1.2.dist-info/WHEEL

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

borgee_plugin_sdk-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Borgee contributors
+
+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.

borgee_plugin_sdk-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+borgee_plugin_sdk