wbskt 0.9.0b1__tar.gz

wbskt-0.9.0b1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.pytest_cache/

wbskt-0.9.0b1/LICENSE

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

wbskt-0.9.0b1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: wbskt
+Version: 0.9.0b1
+Summary: Connect a Raspberry Pi, script or service to Wbskt: register with a policy PIN, hold a WebSocket open, send readings and receive commands.
+Project-URL: Homepage, https://wbskt.com
+Project-URL: Source, https://github.com/wbskt/Wbskt.Python
+Project-URL: Issues, https://github.com/wbskt/Wbskt.Python/issues
+Project-URL: Protocol, https://github.com/wbskt/Wbskt/blob/master/Docs/Client.Protocol.md
+Author: wbskt
+License-Expression: MIT
+License-File: LICENSE
+Keywords: clients,iot,raspberry-pi,wbskt,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: websockets>=13
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# wbskt
+
+Connect a Raspberry Pi, a script or a service to [Wbskt](https://wbskt.com). The client registers
+once with a policy PIN, holds a WebSocket open, sends readings and receives commands. It comes back
+on its own after a drop.
+
+```sh
+pip install wbskt
+```
+
+Python 3.10 or later. The only dependency is `websockets`. This is a 0.9 beta: the client protocol
+it speaks may still change before 1.0.
+
+## Quick start
+
+```python
+from wbskt import WbsktClient
+
+client = WbsktClient("greenhouse-sensor", policy_pin="483920")
+client.on_message = lambda message: print("got", message.type, message.payload)
+client.start()
+
+client.send("temperature", {"celsius": 21.5})
+```
+
+Get the PIN from a registration policy in the console (**Policies**). The first run registers the
+client and stores its credentials in your user data folder (`~/.local/share/wbskt/<name>.json` on
+Linux), so later runs sign in without registering again. If the policy needs approval, the client
+waits and connects once someone approves it in the console.
+
+To keep a script running until Ctrl+C, call `client.run_forever()` instead of `start()`.
+
+## asyncio
+
+```python
+import asyncio
+from wbskt import AsyncWbsktClient
+
+async def main():
+    client = AsyncWbsktClient("greenhouse-sensor", policy_pin="483920")
+
+    async def handle(message):
+        print(message.type, message.payload)
+
+    client.on_message = handle
+    await client.start()
+    while True:
+        await client.send("temperature", {"celsius": read_sensor()})
+        await asyncio.sleep(10)
+
+asyncio.run(main())
+```
+
+Both clients take the same options.
+
+## Commands
+
+Tell the console which commands the client takes, and it offers them with a form:
+
+```python
+from wbskt import Command, DataType, Parameter, WbsktClient
+
+relay = Command("relay.set", "Switch the relay", [Parameter("on", DataType.BOOLEAN, is_required=True)])
+client = WbsktClient("greenhouse-relay", policy_pin="483920", capabilities=[relay])
+
+def handle(message):
+    if message.type == "relay.set":
+        set_relay(message.payload["on"])
+        client.send("relay.state", {"on": message.payload["on"]})
+
+client.on_message = handle
+```
+
+The SDK confirms delivery of a command as soon as it arrives, before your handler runs, and refuses
+one that arrives after its expiry without calling your handler. Report the outcome as a message of
+your own if it matters. Call `set_capabilities(...)` when the set of commands changes.
+
+## Version
+
+Pass `firmware_version="2.4.1"` to say which version of your own code the client runs. The console
+shows it on the client page. It is not the SDK's version, which is sent for you.
+
+## State
+
+```python
+client.report_state({"humidity": 41, "fan": "on"})
+```
+
+Send only what changed. Numbers are kept as readings and charted in the console.
+
+## While offline
+
+`send` never blocks on the network. While disconnected, messages wait in memory (the last 1,000 by
+default, `offline_buffer_size=`) and go out in order, with the time they were made, once the
+connection is back. Workflows can tell those late readings from live ones.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `api_url` | `https://api.dev.wbskt.com` | A self-hosted install's `https://api.<domain>`. |
+| `socket_url` | `wss://ws.dev.wbskt.com` | `wss://ws.<domain>`. |
+| `storage` | `FileStorage.for_client(name)` | `FileStorage(path)`, `MemoryStorage(ref, secret)`, or your own object with `load`, `save` and `clear`. |
+| `capabilities` | none | The commands the client takes. |
+| `offline_buffer_size` | 1000 | Messages kept while offline; the oldest go first. |
+
+Handlers can be `on_message(message)`, `on_connected()` and `on_disconnected()`. On `WbsktClient`
+they run on the client's background thread, so keep them short.
+
+Messages are at most 64 KB, and types starting with `sys.`, `capabilities` and `state.report` are
+reserved; `send` raises `ValueError` for either.
+
+## Protocol
+
+The SDK implements [the client protocol](https://github.com/wbskt/Wbskt/blob/master/Docs/Client.Protocol.md)
+and its [WebSocket binding](https://github.com/wbskt/Wbskt/blob/master/Docs/Client.Protocol.WebSocket.md):
+token reuse, jittered reconnects that honour `Retry-After`, ping answers and command
+acknowledgements. Read it to write a client in another language.

wbskt-0.9.0b1/README.md

@@ -0,0 +1,118 @@
+# wbskt
+
+Connect a Raspberry Pi, a script or a service to [Wbskt](https://wbskt.com). The client registers
+once with a policy PIN, holds a WebSocket open, sends readings and receives commands. It comes back
+on its own after a drop.
+
+```sh
+pip install wbskt
+```
+
+Python 3.10 or later. The only dependency is `websockets`. This is a 0.9 beta: the client protocol
+it speaks may still change before 1.0.
+
+## Quick start
+
+```python
+from wbskt import WbsktClient
+
+client = WbsktClient("greenhouse-sensor", policy_pin="483920")
+client.on_message = lambda message: print("got", message.type, message.payload)
+client.start()
+
+client.send("temperature", {"celsius": 21.5})
+```
+
+Get the PIN from a registration policy in the console (**Policies**). The first run registers the
+client and stores its credentials in your user data folder (`~/.local/share/wbskt/<name>.json` on
+Linux), so later runs sign in without registering again. If the policy needs approval, the client
+waits and connects once someone approves it in the console.
+
+To keep a script running until Ctrl+C, call `client.run_forever()` instead of `start()`.
+
+## asyncio
+
+```python
+import asyncio
+from wbskt import AsyncWbsktClient
+
+async def main():
+    client = AsyncWbsktClient("greenhouse-sensor", policy_pin="483920")
+
+    async def handle(message):
+        print(message.type, message.payload)
+
+    client.on_message = handle
+    await client.start()
+    while True:
+        await client.send("temperature", {"celsius": read_sensor()})
+        await asyncio.sleep(10)
+
+asyncio.run(main())
+```
+
+Both clients take the same options.
+
+## Commands
+
+Tell the console which commands the client takes, and it offers them with a form:
+
+```python
+from wbskt import Command, DataType, Parameter, WbsktClient
+
+relay = Command("relay.set", "Switch the relay", [Parameter("on", DataType.BOOLEAN, is_required=True)])
+client = WbsktClient("greenhouse-relay", policy_pin="483920", capabilities=[relay])
+
+def handle(message):
+    if message.type == "relay.set":
+        set_relay(message.payload["on"])
+        client.send("relay.state", {"on": message.payload["on"]})
+
+client.on_message = handle
+```
+
+The SDK confirms delivery of a command as soon as it arrives, before your handler runs, and refuses
+one that arrives after its expiry without calling your handler. Report the outcome as a message of
+your own if it matters. Call `set_capabilities(...)` when the set of commands changes.
+
+## Version
+
+Pass `firmware_version="2.4.1"` to say which version of your own code the client runs. The console
+shows it on the client page. It is not the SDK's version, which is sent for you.
+
+## State
+
+```python
+client.report_state({"humidity": 41, "fan": "on"})
+```
+
+Send only what changed. Numbers are kept as readings and charted in the console.
+
+## While offline
+
+`send` never blocks on the network. While disconnected, messages wait in memory (the last 1,000 by
+default, `offline_buffer_size=`) and go out in order, with the time they were made, once the
+connection is back. Workflows can tell those late readings from live ones.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `api_url` | `https://api.dev.wbskt.com` | A self-hosted install's `https://api.<domain>`. |
+| `socket_url` | `wss://ws.dev.wbskt.com` | `wss://ws.<domain>`. |
+| `storage` | `FileStorage.for_client(name)` | `FileStorage(path)`, `MemoryStorage(ref, secret)`, or your own object with `load`, `save` and `clear`. |
+| `capabilities` | none | The commands the client takes. |
+| `offline_buffer_size` | 1000 | Messages kept while offline; the oldest go first. |
+
+Handlers can be `on_message(message)`, `on_connected()` and `on_disconnected()`. On `WbsktClient`
+they run on the client's background thread, so keep them short.
+
+Messages are at most 64 KB, and types starting with `sys.`, `capabilities` and `state.report` are
+reserved; `send` raises `ValueError` for either.
+
+## Protocol
+
+The SDK implements [the client protocol](https://github.com/wbskt/Wbskt/blob/master/Docs/Client.Protocol.md)
+and its [WebSocket binding](https://github.com/wbskt/Wbskt/blob/master/Docs/Client.Protocol.WebSocket.md):
+token reuse, jittered reconnects that honour `Retry-After`, ping answers and command
+acknowledgements. Read it to write a client in another language.

wbskt-0.9.0b1/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wbskt"
+dynamic = ["version"]
+description = "Connect a Raspberry Pi, script or service to Wbskt: register with a policy PIN, hold a WebSocket open, send readings and receive commands."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "wbskt" }]
+keywords = ["wbskt", "iot", "websocket", "raspberry-pi", "clients"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+  "Operating System :: OS Independent",
+  "Topic :: Home Automation",
+  "Framework :: AsyncIO",
+]
+dependencies = ["websockets>=13"]
+
+[project.urls]
+Homepage = "https://wbskt.com"
+Source = "https://github.com/wbskt/Wbskt.Python"
+Issues = "https://github.com/wbskt/Wbskt.Python/issues"
+Protocol = "https://github.com/wbskt/Wbskt/blob/master/Docs/Client.Protocol.md"
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[tool.hatch.version]
+path = "src/wbskt/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/wbskt", "tests", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wbskt"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]

wbskt-0.9.0b1/src/wbskt/__init__.py

@@ -0,0 +1,25 @@
+"""Connect a client to Wbskt. See README.md, and Docs/Client.Protocol.md for the wire protocol."""
+
+from .client import DEFAULT_API_URL, DEFAULT_SOCKET_URL, AsyncWbsktClient, WbsktClient
+from .models import Command, DataType, Message, Parameter, RegistrationRequired, WbsktError
+from .reconnect import ReconnectPolicy
+from .storage import FileStorage, MemoryStorage, Storage
+from .version import __version__
+
+__all__ = [
+    "AsyncWbsktClient",
+    "Command",
+    "DataType",
+    "DEFAULT_API_URL",
+    "DEFAULT_SOCKET_URL",
+    "FileStorage",
+    "MemoryStorage",
+    "Message",
+    "Parameter",
+    "ReconnectPolicy",
+    "RegistrationRequired",
+    "Storage",
+    "WbsktClient",
+    "WbsktError",
+    "__version__",
+]

wbskt-0.9.0b1/src/wbskt/_http.py

@@ -0,0 +1,36 @@
+"""The two HTTPS calls a client makes, on the standard library so the SDK has one dependency."""
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Mapping, Optional, Tuple
+
+Response = Tuple[int, Any, Mapping[str, str]]
+
+TIMEOUT = 30.0
+
+
+def post_json(url: str, body: Dict[str, Any], timeout: float = TIMEOUT) -> Response:
+    """POST ``body`` as JSON. Returns the status, the parsed body (None if it isn't JSON) and the headers.
+
+    An HTTP error status is returned, not raised; a network failure raises ``OSError``.
+    """
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(body).encode("utf-8"),
+        headers={"Content-Type": "application/json", "Accept": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.status, _parse(response.read()), dict(response.headers)
+    except urllib.error.HTTPError as error:
+        with error:
+            return error.code, _parse(error.read()), dict(error.headers or {})
+
+
+def _parse(raw: bytes) -> Optional[Any]:
+    try:
+        return json.loads(raw) if raw else None
+    except ValueError:
+        return None

wbskt-0.9.0b1/src/wbskt/_pacing.py

@@ -0,0 +1,24 @@
+"""A token bucket that paces the client's sends below the gateway's message budget."""
+
+import asyncio
+import time
+
+
+class Pacer:
+    """``burst`` sends back to back, then ``per_second``. Single event loop only."""
+
+    def __init__(self, per_second: float, burst: int) -> None:
+        self._per_second = max(0.1, per_second)
+        self._burst = max(1, burst)
+        self._tokens = float(self._burst)
+        self._last = time.monotonic()
+
+    async def take(self) -> None:
+        while True:
+            now = time.monotonic()
+            self._tokens = min(self._burst, self._tokens + (now - self._last) * self._per_second)
+            self._last = now
+            if self._tokens >= 1:
+                self._tokens -= 1
+                return
+            await asyncio.sleep((1 - self._tokens) / self._per_second)