simpleiot 0.1.0__py3-none-any.whl

simpleiot/__init__.py

@@ -0,0 +1,47 @@
+"""A Python client for Simple IoT.
+
+Connect with the shared token, read and write nodes and points, and watch
+for changes::
+
+    import asyncio
+    import simpleiot
+
+    async def main():
+        async with await simpleiot.connect() as c:
+            root = await c.get_root()
+            print(root.description)
+
+    asyncio.run(main())
+"""
+
+from .client import Client, PointsMessage, Subscription, connect
+from .codec import (
+    DataType,
+    Node,
+    NotFoundError,
+    Point,
+    SiotError,
+    decode_nodes,
+    decode_points,
+    encode_points,
+)
+from .ids import new_id, valid_id
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "DataType",
+    "Node",
+    "NotFoundError",
+    "Point",
+    "PointsMessage",
+    "SiotError",
+    "Subscription",
+    "connect",
+    "decode_nodes",
+    "decode_points",
+    "encode_points",
+    "new_id",
+    "valid_id",
+]

simpleiot/client.py

@@ -0,0 +1,449 @@
+"""A Simple IoT client over NATS.
+
+The client connects with the shared token (``SIOT_AUTH_TOKEN``), which gives
+it the full subject space described in the API reference:
+https://docs.simpleiot.org/docs/ref/api.html
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import os
+import time
+from collections.abc import AsyncIterator, Iterable
+from dataclasses import dataclass
+
+import nats
+from nats.aio.client import Client as NATS
+from nats.aio.subscription import Subscription as NatsSubscription
+
+from .codec import (
+    Node,
+    NotFoundError,
+    Point,
+    SiotError,
+    decode_nodes,
+    decode_points,
+    encode_points,
+)
+from .ids import new_id, valid_id
+
+__all__ = ["Client", "PointsMessage", "Subscription", "connect"]
+
+log = logging.getLogger("simpleiot")
+
+DEFAULT_SERVER = "nats://localhost:4222"
+
+# The store answers in milliseconds once it is running, but can take
+# seconds while it recovers streams at start-up. This matches the Go client.
+DEFAULT_TIMEOUT = 20.0
+
+_INVALID_TOKEN_CHARS = set(".*> \t\r\n")
+
+
+async def connect(
+    server: str | None = None,
+    token: str | None = None,
+    **options,
+) -> Client:
+    """Connects to a Simple IoT instance.
+
+    ``server`` defaults to ``SIOT_NATS_SERVER``, then ``nats://localhost:4222``.
+    ``token`` defaults to ``SIOT_AUTH_TOKEN``; an instance with no token set
+    accepts a connection without one. Other options are passed to
+    ``nats.connect``.
+
+    The first connection attempt raises if the server cannot be reached or
+    refuses the token. Once connected, the client reconnects without limit
+    by default. Connection errors are logged to the ``simpleiot`` logger.
+    """
+    server = server or os.environ.get("SIOT_NATS_SERVER") or DEFAULT_SERVER
+    if token is None:
+        token = os.environ.get("SIOT_AUTH_TOKEN") or None
+    allow_reconnect = options.pop("allow_reconnect", True)
+    max_reconnect = options.pop("max_reconnect_attempts", -1)
+    wait = options.pop("reconnect_time_wait", 2)
+    options.setdefault("error_cb", _log_error)
+    # nats-py retries the first connection under the reconnect settings, so
+    # with no limit a server that is down would hang here. Try twice, then
+    # apply the caller's settings once connected.
+    nc = await nats.connect(
+        servers=[server],
+        token=token,
+        allow_reconnect=False,
+        max_reconnect_attempts=1,
+        reconnect_time_wait=0.2,
+        **options,
+    )
+    nc.options["allow_reconnect"] = allow_reconnect
+    nc.options["max_reconnect_attempts"] = max_reconnect
+    nc.options["reconnect_time_wait"] = wait
+    return Client(nc)
+
+
+async def _log_error(e: Exception) -> None:
+    log.warning("nats: %s", e)
+
+
+@dataclass
+class PointsMessage:
+    """Points received on a subscription.
+
+    ``parent_id`` is set for edge points and empty for node points. For an
+    ``up`` subject, ``upstream_id`` is the ancestor the points were fanned
+    out to.
+    """
+
+    subject: str
+    node_id: str
+    parent_id: str
+    type: str
+    key: str
+    points: list[Point]
+    upstream_id: str = ""
+
+    @property
+    def is_edge(self) -> bool:
+        return self.parent_id != ""
+
+
+def parse_subject(subject: str) -> dict[str, str]:
+    """Splits a point subject into its parts.
+
+    ::
+
+        p.<node>.<type>.<key>
+        ep.<node>.<parent>.<type>.<key>
+        up.<upstream>.<node>.<type>.<key>
+        up.<upstream>.<node>.<parent>.<type>.<key>
+    """
+    t = subject.split(".")
+    ret = {"upstream_id": "", "node_id": "", "parent_id": "", "type": "", "key": ""}
+    if t[0] == "up" and len(t) == 6:
+        ret.update(upstream_id=t[1], node_id=t[2], parent_id=t[3], type=t[4], key=t[5])
+    elif t[0] == "up" and len(t) == 5:
+        ret.update(upstream_id=t[1], node_id=t[2], type=t[3], key=t[4])
+    elif t[0] == "ep" and len(t) >= 3:
+        ret.update(node_id=t[1], parent_id=t[2])
+        if len(t) == 5:
+            ret.update(type=t[3], key=t[4])
+    elif t[0] == "p" and len(t) == 4:
+        ret.update(node_id=t[1], type=t[2], key=t[3])
+    return ret
+
+
+class Subscription:
+    """Decoded point messages from a NATS subscription.
+
+    Iterate with ``async for msg in sub`` and stop with ``await
+    sub.unsubscribe()``, or use it as an async context manager.
+    """
+
+    def __init__(self, sub: NatsSubscription) -> None:
+        self._sub = sub
+
+    @property
+    def subject(self) -> str:
+        return self._sub.subject
+
+    async def __aiter__(self) -> AsyncIterator[PointsMessage]:
+        async for m in self._sub.messages:
+            try:
+                points = decode_points(m.data)
+            except ValueError:
+                continue
+            yield PointsMessage(subject=m.subject, points=points, **parse_subject(m.subject))
+
+    async def unsubscribe(self) -> None:
+        await self._sub.unsubscribe()
+
+    async def __aenter__(self) -> Subscription:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.unsubscribe()
+
+
+def _check_token(what: str, s: str) -> None:
+    if not s or any(c in _INVALID_TOKEN_CHARS for c in s):
+        raise ValueError(f"{what} {s!r} may not be empty or contain '.', '*', '>', or whitespace")
+
+
+def _check_reply(data: bytes) -> None:
+    if data:
+        raise SiotError(data.decode(errors="replace"))
+
+
+class Client:
+    """A connection to a Simple IoT instance. Create one with :func:`connect`."""
+
+    def __init__(self, nc: NATS, timeout: float = DEFAULT_TIMEOUT) -> None:
+        self.nc = nc
+        self.timeout = timeout
+
+    async def close(self) -> None:
+        """Flushes pending messages and closes the connection."""
+        await self.nc.drain()
+
+    async def __aenter__(self) -> Client:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+    # --- reading nodes ---
+
+    async def get_nodes(
+        self,
+        parent: str,
+        id: str = "all",
+        *,
+        type: str = "",
+        include_deleted: bool = False,
+        depth: int = 0,
+    ) -> list[Node]:
+        """Fetches nodes, as the ``nodes.<parent>.<id>`` request.
+
+        - ``parent="all"`` returns every instance of node ``id``, one per edge.
+        - ``id="all"`` returns the children of ``parent``.
+        - ``parent="root", id="all"`` returns the root node.
+
+        ``type`` keeps only nodes of that type, ``include_deleted`` includes
+        deleted ones, and ``depth`` also returns descendants that many levels
+        down, in one flat list placed by each node's ``parent``.
+        """
+        params: list[Point] = []
+        if include_deleted:
+            params.append(Point("tombstone", 1))
+        if type:
+            params.append(Point("nodeType", type))
+        if depth > 0:
+            params.append(Point("depth", depth))
+        m = await self.nc.request(
+            f"nodes.{parent or 'all'}.{id or 'all'}", encode_points(params), timeout=self.timeout
+        )
+        try:
+            return decode_nodes(m.data)
+        except NotFoundError:
+            return []
+
+    async def get_node(self, id: str, parent: str = "all") -> Node:
+        """Returns one node. Raises :class:`NotFoundError` when it does not exist.
+
+        A node that sits in several places in the tree is returned under the
+        first of its parents unless ``parent`` names one.
+        """
+        nodes = await self.get_nodes(parent, id)
+        if not nodes:
+            raise NotFoundError(f"node {id} not found")
+        return nodes[0]
+
+    async def get_children(
+        self, parent: str, *, type: str = "", include_deleted: bool = False
+    ) -> list[Node]:
+        """Returns the children of a node."""
+        return await self.get_nodes(parent, "all", type=type, include_deleted=include_deleted)
+
+    async def get_root(self) -> Node:
+        """Returns the root node of the instance."""
+        nodes = await self.get_nodes("root", "all")
+        if not nodes:
+            raise NotFoundError("root node not found")
+        return nodes[0]
+
+    async def search(self, below: str, query: str, *, limit: int = 0, type: str = "") -> list[Node]:
+        """Finds nodes below ``below`` whose description, ID, or type matches.
+
+        The reply carries each match and its ancestors below ``below``.
+        ``limit`` caps the matches (20 by default, 100 at most).
+        """
+        params = [Point("search", query)]
+        if limit > 0:
+            params.append(Point("limit", limit))
+        if type:
+            params.append(Point("nodeType", type))
+        m = await self.nc.request(f"nodes.{below}.all", encode_points(params), timeout=self.timeout)
+        return decode_nodes(m.data)
+
+    # --- writing points ---
+
+    async def send_points(self, node_id: str, points: Iterable[Point], *, ack: bool = True) -> None:
+        """Writes points to a node.
+
+        Each point is its own message on ``p.<node>.<type>.<key>``. With
+        ``ack`` the call waits for the store to accept each point and raises
+        :class:`SiotError` if it refuses one.
+        """
+        _check_token("node ID", node_id)
+        for p in points:
+            _check_token("point type", p.type)
+            _check_token("point key", p.key or "0")
+            subject = f"p.{node_id}.{p.type}.{p.key or '0'}"
+            await self._send(subject, [p], ack)
+
+    async def send_point(self, node_id: str, type: str, value, key: str = "0", **kw) -> None:
+        """Writes a single point to a node. Extra arguments go to :class:`Point`."""
+        await self.send_points(node_id, [Point(type, value, key=key, **kw)])
+
+    async def send_edge_points(
+        self, node_id: str, parent: str, points: Iterable[Point], *, ack: bool = True
+    ) -> None:
+        """Writes points to the edge between a node and its parent, in one message."""
+        _check_token("node ID", node_id)
+        _check_token("parent ID", parent)
+        await self._send(f"ep.{node_id}.{parent}", list(points), ack)
+
+    async def _send(self, subject: str, points: list[Point], ack: bool) -> None:
+        data = encode_points(points)
+        if ack:
+            m = await self.nc.request(subject, data, timeout=self.timeout)
+            _check_reply(m.data)
+        else:
+            await self.nc.publish(subject, data)
+
+    # --- creating and removing nodes ---
+
+    async def create_node(
+        self,
+        parent: str,
+        type: str,
+        points: Iterable[Point] = (),
+        *,
+        id: str | None = None,
+        description: str | None = None,
+        primary: bool = False,
+    ) -> str:
+        """Creates a node under ``parent`` and returns its ID.
+
+        ``id`` defaults to a new random ID. ``description`` is a shortcut for
+        a description point. Set ``primary`` for a node type that owns
+        hardware or a connection (Modbus, serial, sync, and the like), so its
+        client runs on this edge only; see "Primary and mirror edges" in the
+        data reference.
+
+        Sending to an existing ID and parent updates that node.
+        """
+        id = id or new_id()
+        if not valid_id(id):
+            raise ValueError(f"invalid node ID {id!r}")
+        pts = list(points)
+        if description is not None:
+            pts.append(Point("description", description))
+        await self.send_points(id, pts)
+        edge = [Point("tombstone", 0), Point("nodeType", type)]
+        if primary:
+            edge.append(Point("primary", 1))
+        await self.send_edge_points(id, parent, edge)
+        return id
+
+    async def delete_node(self, id: str, parent: str) -> None:
+        """Removes a node from ``parent``.
+
+        Deleting a node's primary edge also deletes its mirrors, as the web
+        UI does. The node can be restored by setting the edge tombstone back
+        to 0.
+        """
+        nodes = await self.get_nodes("all", id)
+        tomb = [Point("tombstone", 1)]
+        here = next((n for n in nodes if n.parent == parent), None)
+        if here is not None and _role_set(here, "primary"):
+            for n in nodes:
+                if n.parent != parent and _role_set(n, "mirror"):
+                    await self.send_edge_points(id, n.parent, tomb)
+        await self.send_edge_points(id, parent, tomb)
+
+    async def move_node(self, id: str, old_parent: str, new_parent: str) -> None:
+        """Moves a node from one parent to another, keeping its edge role."""
+        nodes = await self.get_nodes(old_parent, id)
+        if not nodes:
+            raise NotFoundError(f"node {id} not found under {old_parent}")
+        n = nodes[0]
+        edge = [Point("tombstone", 0), Point("nodeType", n.type)]
+        for role in ("primary", "mirror"):
+            if _role_set(n, role):
+                edge.append(Point(role, 1))
+        await self.send_edge_points(id, new_parent, edge)
+        await self.send_edge_points(id, old_parent, [Point("tombstone", 1)])
+
+    # --- provisioning ---
+
+    async def provision(self, name: str, contents: str, *, timeout: float = 30.0) -> str:
+        """Uploads a YAML node file for the server to apply, and waits until it has.
+
+        The file is a ``file`` node called ``name`` under the instance's
+        ``provisioning`` node, which is created if there is none. The server
+        applies it the way ``siot import`` does: nodes are matched by
+        description, missing ones are created, and changed points are
+        updated. It applies the file again only when its contents change.
+
+        Returns the file node's ID. Raises :class:`SiotError` with the
+        server's message if the file fails to apply, and ``TimeoutError`` if
+        it is not applied within ``timeout`` seconds. See "Configuration
+        provisioning" in the configuration guide.
+        """
+        want = hashlib.sha256(contents.encode()).hexdigest()
+        root = await self.get_root()
+        provs = await self.get_children(root.id, type="provisioning")
+        if provs:
+            prov = provs[0].id
+        else:
+            prov = await self.create_node(
+                root.id, "provisioning", description="Provisioning", primary=True
+            )
+
+        file = next(
+            (
+                f
+                for f in await self.get_children(prov, type="file")
+                if name in (f.value("name"), f.description)
+            ),
+            None,
+        )
+        if file is None:
+            id = await self.create_node(
+                prov,
+                "file",
+                [Point("name", name), Point("created", int(time.time())), Point("data", contents)],
+                description=name,
+            )
+        else:
+            id = file.id
+            if file.value("data") != contents:
+                await self.send_point(id, "data", contents)
+
+        # the server records the hash of what it tried, with the error, after
+        # each attempt
+        deadline = time.monotonic() + timeout
+        while True:
+            n = await self.get_node(id, prov)
+            if n.value("provisionHash") == want:
+                err = n.value("error", default="")
+                if err:
+                    raise SiotError(f"provisioning {name}: {err}")
+                return id
+            if time.monotonic() > deadline:
+                raise TimeoutError(f"provisioning {name} was not applied within {timeout} s")
+            await asyncio.sleep(0.2)
+
+    # --- subscriptions ---
+
+    async def subscribe(self, subject: str) -> Subscription:
+        """Subscribes to any point subject and returns decoded messages."""
+        return Subscription(await self.nc.subscribe(subject))
+
+    async def subscribe_node(self, id: str) -> Subscription:
+        """Subscribes to the node points of one node, after the store accepts them."""
+        _check_token("node ID", id)
+        return await self.subscribe(f"up.{id}.{id}.*.*")
+
+    async def subscribe_tree(self, id: str) -> Subscription:
+        """Subscribes to every node and edge point at or below a node."""
+        _check_token("node ID", id)
+        return await self.subscribe(f"up.{id}.>")
+
+
+def _role_set(n: Node, role: str) -> bool:
+    p = n.edge_point(role)
+    return p is not None and p.bool

simpleiot/codec.py

@@ -0,0 +1,372 @@
+"""Points, nodes, and their binary wire encoding.
+
+This mirrors ``data/point.go`` and ``data/node.go`` in the Go code. Integers
+are little endian, strings and byte fields carry a two-byte length, time is
+int64 nanoseconds since the epoch, and a node reply starts with a version
+byte and an error string.
+
+The tests check this module against the fixtures ``data/point_fixture_test.go``
+writes, so the Python and Go encoders cannot drift without a test failing.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from enum import IntEnum
+from typing import Any
+
+__all__ = [
+    "DataType",
+    "Node",
+    "Point",
+    "SiotError",
+    "NotFoundError",
+    "decode_nodes",
+    "decode_points",
+    "encode_points",
+]
+
+NODE_FRAME_VERSION = 1
+MAX_POINTS_PER_MESSAGE = 10000
+MAX_NODES_PER_FRAME = 10000
+
+# the error string the server sends when a node does not exist
+# (data.ErrDocumentNotFound)
+_NOT_FOUND = "document not found"
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+
+class SiotError(Exception):
+    """An error reported by the Simple IoT server."""
+
+
+class NotFoundError(SiotError):
+    """The requested node does not exist."""
+
+
+class DataType(IntEnum):
+    """How a point's value is encoded, as ``data.PointDataType``."""
+
+    UNKNOWN = 0
+    FLOAT = 1
+    INT = 2
+    STRING = 3
+    JSON = 4
+
+
+Value = float | int | str | bool | dict | list | bytes | None
+
+
+@dataclass
+class Point:
+    """A single value on a node or an edge.
+
+    ``value`` sets both the data and its type when sending: a ``str`` is a
+    string point, a ``dict`` or ``list`` is a JSON point, and a number or
+    ``bool`` is a float point. Pass ``data_type=DataType.INT`` to send an
+    integer as an int point, or ``DataType.JSON`` to send a string that
+    already holds JSON. ``None`` sends a point with no value.
+
+    A missing ``time`` is filled in with the current time when the point is
+    sent. ``key`` separates points of the same type, such as the channels of
+    an input; most points use ``"0"``.
+    """
+
+    type: str
+    value: Value = None
+    key: str = "0"
+    time: datetime | None = None
+    tombstone: int = 0
+    origin: str = ""
+    data_type: DataType | None = None
+
+    @property
+    def number(self) -> float:
+        """The numeric value, or 0 for a point that is not a number.
+
+        This matches ``Point.Val()`` in Go. A ``bool`` value reads as 1 or 0.
+        """
+        v = self.value
+        if isinstance(v, bool):
+            return 1.0 if v else 0.0
+        if isinstance(v, (int, float)):
+            return float(v)
+        return 0.0
+
+    @property
+    def text(self) -> str:
+        """The string value, or ``""`` for a point that is not a string.
+
+        This matches ``Point.Txt()`` in Go. A JSON point returns its JSON text.
+        """
+        dt, data = _point_data(self)
+        if dt in (DataType.STRING, DataType.JSON):
+            return data.decode()
+        return ""
+
+    @property
+    def bool(self) -> bool:
+        """True when the numeric value is 1, as ``Point.Bool()`` in Go."""
+        return self.number == 1
+
+    @property
+    def deleted(self) -> bool:
+        """True when the point has been deleted (its tombstone is set)."""
+        return self.tombstone != 0
+
+
+@dataclass
+class Node:
+    """A node and the edge points that place it under ``parent``."""
+
+    id: str
+    type: str
+    parent: str = ""
+    points: list[Point] = field(default_factory=list)
+    edge_points: list[Point] = field(default_factory=list)
+
+    def point(self, type: str, key: str = "0") -> Point | None:
+        """Returns the node point with this type and key, or None."""
+        return _find(self.points, type, key)
+
+    def edge_point(self, type: str, key: str = "0") -> Point | None:
+        """Returns the edge point with this type and key, or None."""
+        return _find(self.edge_points, type, key)
+
+    def value(self, type: str, key: str = "0", default: Any = None) -> Any:
+        """Returns the value of a node point, or ``default`` when it is missing."""
+        p = self.point(type, key)
+        if p is None or p.deleted:
+            return default
+        return p.value
+
+    @property
+    def description(self) -> str:
+        """The node's description, or ``""``."""
+        p = self.point("description")
+        return p.text if p else ""
+
+    @property
+    def deleted(self) -> bool:
+        """True when the edge to ``parent`` has been deleted."""
+        p = self.edge_point("tombstone")
+        return p is not None and p.bool
+
+
+def _norm_key(key: str) -> str:
+    # the store keeps an empty key as "0"
+    return key or "0"
+
+
+def _find(points: list[Point], type: str, key: str) -> Point | None:
+    key = _norm_key(key)
+    for p in points:
+        if p.type == type and _norm_key(p.key) == key:
+            return p
+    return None
+
+
+def _int_bytes(v: int) -> bytes:
+    # the smallest width that holds the value, as data.Point.PutInt
+    if -(1 << 7) <= v < (1 << 7):
+        return struct.pack("<b", v)
+    if -(1 << 15) <= v < (1 << 15):
+        return struct.pack("<h", v)
+    if -(1 << 31) <= v < (1 << 31):
+        return struct.pack("<i", v)
+    return struct.pack("<q", v)
+
+
+def _point_data(p: Point) -> tuple[DataType, bytes]:
+    v = p.value
+    dt = p.data_type
+    if v is None:
+        return DataType.UNKNOWN, b""
+    if isinstance(v, bytes):
+        return (dt if dt is not None else DataType.UNKNOWN), v
+    if isinstance(v, str):
+        return (DataType.JSON if dt == DataType.JSON else DataType.STRING), v.encode()
+    if isinstance(v, (dict, list)):
+        return DataType.JSON, json.dumps(v, separators=(",", ":")).encode()
+    if isinstance(v, bool):
+        v = 1 if v else 0
+    if isinstance(v, (int, float)):
+        if dt == DataType.INT:
+            if isinstance(v, float) and not v.is_integer():
+                raise ValueError(f"point {p.type}: {v} is not an integer")
+            return DataType.INT, _int_bytes(int(v))
+        return DataType.FLOAT, struct.pack("<d", float(v))
+    raise TypeError(f"point {p.type}: unsupported value type {type(v).__name__}")
+
+
+def _to_nanos(t: datetime | None) -> int:
+    if t is None:
+        t = datetime.now(timezone.utc)
+    elif t.tzinfo is None:
+        t = t.astimezone()
+    d = t - _EPOCH
+    return (d.days * 86400 + d.seconds) * 1_000_000_000 + d.microseconds * 1000
+
+
+def _from_nanos(ns: int) -> datetime:
+    return _EPOCH + timedelta(microseconds=ns // 1000)
+
+
+def _decode_value(dt: int, data: bytes) -> Value:
+    if dt == DataType.FLOAT:
+        if len(data) == 8:
+            return struct.unpack("<d", data)[0]
+        if len(data) == 4:
+            return struct.unpack("<f", data)[0]
+        return 0.0
+    if dt == DataType.INT:
+        fmt = {1: "<b", 2: "<h", 4: "<i", 8: "<q"}.get(len(data))
+        return struct.unpack(fmt, data)[0] if fmt else 0
+    if dt in (DataType.STRING, DataType.JSON):
+        return data.decode()
+    if not data:
+        return None
+    return data
+
+
+class _Writer:
+    def __init__(self) -> None:
+        self.buf = bytearray()
+
+    def u8(self, v: int) -> None:
+        self.buf.append(v & 0xFF)
+
+    def u32(self, v: int) -> None:
+        self.buf += struct.pack("<I", v & 0xFFFFFFFF)
+
+    def i64(self, v: int) -> None:
+        self.buf += struct.pack("<q", v)
+
+    def bytes(self, b: bytes) -> None:
+        if len(b) > 0xFFFF:
+            raise ValueError(f"field of {len(b)} bytes is too long to encode")
+        self.buf += struct.pack("<H", len(b))
+        self.buf += b
+
+    def string(self, s: str) -> None:
+        self.bytes(s.encode())
+
+
+class _Reader:
+    def __init__(self, data: bytes) -> None:
+        self.data = memoryview(data)
+        self.off = 0
+
+    def _take(self, n: int, what: str) -> memoryview:
+        if self.off + n > len(self.data):
+            raise ValueError(f"decode: not enough data for {what} at offset {self.off}")
+        b = self.data[self.off : self.off + n]
+        self.off += n
+        return b
+
+    def u8(self) -> int:
+        return self._take(1, "byte")[0]
+
+    def u32(self) -> int:
+        return struct.unpack("<I", self._take(4, "count"))[0]
+
+    def i32(self) -> int:
+        return struct.unpack("<i", self._take(4, "int32"))[0]
+
+    def i64(self) -> int:
+        return struct.unpack("<q", self._take(8, "time"))[0]
+
+    def bytes(self) -> bytes:
+        n = struct.unpack("<H", self._take(2, "length"))[0]
+        return bytes(self._take(n, "bytes"))
+
+    def string(self) -> str:
+        return self.bytes().decode()
+
+
+def _encode_points_to(w: _Writer, points: list[Point]) -> None:
+    w.u32(len(points))
+    for p in points:
+        dt, data = _point_data(p)
+        w.string(p.type)
+        w.string(p.key)
+        w.i64(_to_nanos(p.time))
+        w.u8(dt)
+        w.bytes(data)
+        w.u32(p.tombstone)
+        w.string(p.origin)
+
+
+def _decode_points_from(r: _Reader) -> list[Point]:
+    count = r.u32()
+    if count > MAX_POINTS_PER_MESSAGE:
+        raise ValueError(f"decode: point count {count} exceeds maximum")
+    points = []
+    for _ in range(count):
+        typ = r.string()
+        key = r.string() or "0"
+        t = _from_nanos(r.i64())
+        dt = r.u8()
+        data = r.bytes()
+        tombstone = r.i32()
+        origin = r.string()
+        points.append(
+            Point(
+                type=typ,
+                key=key,
+                time=t,
+                value=_decode_value(dt, data),
+                data_type=DataType(dt) if dt in DataType._value2member_map_ else None,
+                tombstone=tombstone,
+                origin=origin,
+            )
+        )
+    return points
+
+
+def encode_points(points: list[Point]) -> bytes:
+    """Returns the wire encoding of a list of points."""
+    w = _Writer()
+    _encode_points_to(w, points)
+    return bytes(w.buf)
+
+
+def decode_points(data: bytes) -> list[Point]:
+    """Returns the points in a wire payload."""
+    return _decode_points_from(_Reader(data))
+
+
+def decode_nodes(data: bytes) -> list[Node]:
+    """Returns the nodes in a node reply.
+
+    An error the server put in the reply is raised as :class:`SiotError`, or
+    :class:`NotFoundError` when the node does not exist. An empty payload is
+    no nodes.
+    """
+    if not data:
+        return []
+    r = _Reader(data)
+    version = r.u8()
+    if version != NODE_FRAME_VERSION:
+        raise ValueError(f"decode: unsupported node frame version {version}")
+    err = r.string()
+    if err == _NOT_FOUND:
+        raise NotFoundError(err)
+    if err:
+        raise SiotError(err)
+    count = r.u32()
+    if count > MAX_NODES_PER_FRAME:
+        raise ValueError(f"decode: node count {count} exceeds maximum")
+    nodes = []
+    for _ in range(count):
+        nid = r.string()
+        typ = r.string()
+        parent = r.string()
+        points = _decode_points_from(r)
+        edge_points = _decode_points_from(r)
+        nodes.append(Node(nid, typ, parent, points, edge_points))
+    return nodes

simpleiot/ids.py

@@ -0,0 +1,31 @@
+"""Node IDs, as ``data/id.go``."""
+
+from __future__ import annotations
+
+import base64
+import os
+import re
+
+__all__ = ["new_id", "valid_id"]
+
+# lowercase Crockford base32, the alphabet data.NewID uses
+_STD = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
+_CROCKFORD = "0123456789abcdefghjkmnpqrstvwxyz"
+_TO_CROCKFORD = str.maketrans(_STD, _CROCKFORD)
+
+_VALID = re.compile(r"[A-Za-z0-9][A-Za-z0-9-]{0,63}")
+
+
+def new_id() -> str:
+    """Returns a new random node ID: 128 random bits as 26 characters."""
+    b = base64.b32encode(os.urandom(16)).decode().rstrip("=")
+    return b.translate(_TO_CROCKFORD)
+
+
+def valid_id(id: str) -> bool:
+    """Reports whether an ID chosen by hand is safe to use.
+
+    An ID is 1 to 64 ASCII letters, digits, and ``-``, not starting with
+    ``-``. Other characters would split or corrupt a NATS subject.
+    """
+    return _VALID.fullmatch(id) is not None

simpleiot-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: simpleiot
+Version: 0.1.0
+Summary: Python client for Simple IoT, over NATS
+Project-URL: Homepage, https://simpleiot.org
+Project-URL: Documentation, https://docs.simpleiot.org/python/
+Project-URL: Repository, https://github.com/simpleiot/simpleiot
+Project-URL: Changelog, https://github.com/simpleiot/simpleiot/blob/master/python/CHANGELOG.md
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: iot,nats,simpleiot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Requires-Dist: nats-py>=2.6
+Description-Content-Type: text/markdown
+
+# simpleiot
+
+A Python client for [Simple IoT](https://simpleiot.org). Read and write nodes
+and points, and watch for changes, over the NATS API.
+
+The client connects with the instance's shared token (`SIOT_AUTH_TOKEN`), which
+reaches the whole tree. It suits scripts and services running alongside an
+instance you operate.
+
+![a Python process on an edge device talks to the local SIOT over NATS; the local SIOT syncs with the cloud, and people use the web UI on either instance](https://docs.simpleiot.org/python/images/deployment.svg)
+
+A typical setup runs the Python process next to SIOT on an edge device. What it
+writes reaches the cloud through sync, and a person sees it in the web UI on
+site or remotely.
+
+## Install
+
+```
+pip install simpleiot
+```
+
+Requires Python 3.10 or newer. The client is built on
+[nats-py](https://github.com/nats-io/nats.py) and uses `asyncio`.
+
+## Usage
+
+```python
+import asyncio
+import simpleiot
+from simpleiot import Point
+
+
+async def main():
+    async with await simpleiot.connect() as c:
+        root = await c.get_root()
+        print("root:", root.description)
+
+        id = await c.create_node(root.id, "variable", description="tank level")
+        await c.send_point(id, "value", 42.5)
+
+        async with await c.subscribe_node(id) as sub:
+            async for m in sub:
+                for p in m.points:
+                    print(p.type, p.value)
+
+
+asyncio.run(main())
+```
+
+`connect()` reads `SIOT_NATS_SERVER` (default `nats://localhost:4222`) and
+`SIOT_AUTH_TOKEN` from the environment, or takes them as arguments:
+
+```python
+c = await simpleiot.connect("nats://10.0.0.5:4222", token="...")
+```
+
+## Nodes and points
+
+Data in Simple IoT is a tree of **nodes**, each holding **points**. A point has
+a `type`, a `key` (`"0"` unless a node holds several of a type), a `value`, and
+a `time`. The edge from a node to its parent carries its own points, such as
+`tombstone` for a deleted node. See the
+[data reference](https://docs.simpleiot.org/docs/ref/data.html).
+
+`Point.value` sets the encoding when sending:
+
+| Value                  | Sent as               |
+| ---------------------- | --------------------- |
+| `float`, `int`, `bool` | a float point         |
+| `str`                  | a string point        |
+| `dict`, `list`         | a JSON point          |
+| `None`                 | a point with no value |
+
+Pass `data_type=DataType.INT` to send an integer as an int point. A received
+point's `value` is a `float`, `int`, or `str` by its data type; `number` and
+`text` read it as a number or string either way.
+
+## API
+
+All methods are coroutines on `Client`.
+
+- `get_root()`, `get_node(id, parent="all")`, `get_children(parent, type=...)`
+- `get_nodes(parent, id="all", type=..., include_deleted=..., depth=...)`, the
+  `nodes.<parent>.<id>` request
+- `search(below, query, limit=..., type=...)`
+- `send_points(id, points)`, `send_point(id, type, value, key="0")`
+- `send_edge_points(id, parent, points)`
+- `create_node(parent, type, points, id=..., description=..., primary=...)`
+- `delete_node(id, parent)`, `move_node(id, old_parent, new_parent)`
+- `provision(name, yaml)` uploads a node file for the server to apply, as
+  `siot import` would, and waits until it has
+- `subscribe_node(id)`, `subscribe_tree(id)`, `subscribe(subject)`: async
+  iterators of `PointsMessage`
+- `close()`
+
+A server error raises `SiotError`; a missing node raises `NotFoundError`.
+
+## Examples
+
+Each example is a short script in its own directory with a README:
+
+- [tree](https://github.com/simpleiot/simpleiot/tree/master/python/examples/tree)
+  prints the node tree
+- [send_points](https://github.com/simpleiot/simpleiot/tree/master/python/examples/send_points)
+  creates a node and writes a value to it once a second
+- [watch](https://github.com/simpleiot/simpleiot/tree/master/python/examples/watch)
+  prints every point change below a node
+- [mirror_temperature](https://github.com/simpleiot/simpleiot/tree/master/python/examples/mirror_temperature)
+  reacts to one point by writing another
+- [rover](https://github.com/simpleiot/simpleiot/tree/master/python/examples/rover)
+  drives a simulated autonomous rover from a dashboard, with a live map, status,
+  and commands
+
+Run them against a local instance:
+
+```
+SIOT_AUTH_TOKEN=... python examples/tree/tree.py
+```
+
+## Development
+
+The client lives in the
+[Simple IoT repository](https://github.com/simpleiot/simpleiot) under `python/`,
+so it changes together with the server.
+
+```
+cd python
+uv sync
+uv run pytest
+```
+
+The tests need [uv](https://docs.astral.sh/uv/). The codec tests check the
+encoder against the fixtures `data/point_fixture_test.go` writes, the same ones
+the JavaScript client is checked against. The integration tests start a scratch
+`siot` when `SIOT_BIN` names one; `siot_test_python` in `envsetup.sh` builds it
+and runs them.
+
+To publish a release, set the version in `python/src/simpleiot/__init__.py`, add
+a `python/CHANGELOG.md` entry, and push a `py-v<version>` tag. The
+`Python release` workflow builds the package and publishes it to PyPI.

simpleiot-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+simpleiot/__init__.py,sha256=9Z0epZ2L_yi58ulfLyK2zavq7XWpkov2GLfCKMdrx0c,869
+simpleiot/client.py,sha256=uUt7AbIecd03V9EZ73m8s_vx-qN-g3H7EdV4lLb08Dg,16097
+simpleiot/codec.py,sha256=0LHLHA5jzO-BuiA9Hq1YnkxSBFSWLJlTlvZpLrSxKyo,10986
+simpleiot/ids.py,sha256=tmxhTaB6NIksO_b7SyOXTAilDcDUCUN-zOCm6uHSSiM,876
+simpleiot/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simpleiot-0.1.0.dist-info/METADATA,sha256=HjHKSr9RNhLhywh0yDSThkphY7Eh8b0K9NpdowAPryc,5813
+simpleiot-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+simpleiot-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+simpleiot-0.1.0.dist-info/RECORD,,

simpleiot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

simpleiot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.