i3x-client 0.1.0__tar.gz

i3x_client-0.1.0/LICENSE

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

i3x_client-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: i3x-client
+Version: 0.1.0
+Summary: Python client library for I3X CMIP servers
+Project-URL: Homepage, https://github.com/i3x/i3x-python
+Project-URL: Documentation, https://github.com/i3x/i3x-python#readme
+Project-URL: Issues, https://github.com/i3x/i3x-python/issues
+Author: I3X Working Group
+License-Expression: MIT
+License-File: LICENSE
+Keywords: building-automation,client,cmip,i3x,iot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# i3x-client
+
+Python client library for I3X CMIP servers.
+
+## Installation
+
+```bash
+pip install i3x-client
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import i3x
+
+# Connect to a CMIP server
+client = i3x.Client("http://localhost:8080")
+client.connect()
+
+# Explore the data model
+namespaces = client.get_namespaces()
+object_types = client.get_object_types()
+objects = client.get_objects(type_id="some-type")
+
+# Read values
+value = client.get_value("element-id-1")
+print(value.data[0].value, value.data[0].quality)
+
+# Read historical values
+history = client.get_history("element-id-1", start_time="2026-01-01T00:00:00Z")
+
+# Write values
+client.update_value("element-id-1", {"temperature": 72.5})
+
+# Disconnect
+client.disconnect()
+```
+
+### Context Manager
+
+```python
+with i3x.Client("http://localhost:8080") as client:
+    namespaces = client.get_namespaces()
+```
+
+### Subscriptions
+
+```python
+client = i3x.Client("http://localhost:8080")
+client.on_value_change = lambda client, change: print(f"{change.element_id}: {change.data}")
+client.connect()
+
+# Subscribe to value changes (creates subscription + registers + starts SSE stream)
+sub = client.subscribe(["element-id-1", "element-id-2"])
+
+# ... on_value_change fires automatically when values change ...
+
+# Unsubscribe when done
+client.unsubscribe(sub)
+client.disconnect()
+```
+
+### Authentication
+
+```python
+client = i3x.Client("http://localhost:8080", auth=("api-key", "secret"))
+```
+
+## API Reference
+
+### Client Methods
+
+#### Connection
+- `connect()` — Connect to the server
+- `disconnect()` — Disconnect and stop all subscriptions
+- `is_connected` — Property indicating connection state
+
+#### Callbacks
+- `on_connect(client)` — Called after successful connection
+- `on_disconnect(client)` — Called after disconnection
+- `on_value_change(client, change)` — Called when a subscribed value changes
+- `on_subscribe(client, subscription)` — Called after a subscription is created
+- `on_error(client, error)` — Called on stream/subscription errors
+
+#### Exploration
+- `get_namespaces()` — List all namespaces
+- `get_object_types(namespace_uri=None)` — List object types
+- `query_object_types(element_ids)` — Query types by ID
+- `get_relationship_types(namespace_uri=None)` — List relationship types
+- `query_relationship_types(element_ids)` — Query relationship types by ID
+- `get_objects(type_id=None, include_metadata=False)` — List object instances
+- `get_object(element_id)` — Get a single object
+- `list_objects(element_ids)` — Get multiple objects by ID
+- `get_related_objects(element_ids, relationship_type)` — Get related objects
+
+#### Values
+- `get_value(element_id, max_depth=1)` — Get last known value
+- `get_values(element_ids, max_depth=1)` — Get multiple last known values
+- `get_history(element_id, start_time=None, end_time=None, max_depth=1)` — Get historical values
+
+#### Updates
+- `update_value(element_id, value)` — Update an element's value
+- `update_history(element_id, value)` — Update historical values
+
+#### Subscriptions (High-Level)
+- `subscribe(element_ids, max_depth=0)` — Create subscription + register + start stream
+- `unsubscribe(subscription)` — Stop stream and delete subscription
+- `sync_subscription(subscription)` — Poll queued updates
+
+#### Subscriptions (Low-Level)
+- `create_subscription()` — Create an empty subscription
+- `register_items(subscription_id, element_ids, max_depth=0)` — Register items
+- `unregister_items(subscription_id, element_ids)` — Unregister items
+- `get_subscriptions()` — List all subscriptions
+- `get_subscription(subscription_id)` — Get subscription details
+- `start_stream(subscription_id)` — Start SSE for an existing subscription
+- `stop_stream(subscription_id)` — Stop SSE without deleting subscription
+
+### Models
+
+All models are frozen dataclasses with `from_dict()` classmethods.
+
+- `Namespace` — `uri`, `display_name`
+- `ObjectType` — `element_id`, `display_name`, `namespace_uri`, `schema`
+- `RelationshipType` — `element_id`, `display_name`, `namespace_uri`, `reverse_of`
+- `ObjectInstance` — `element_id`, `display_name`, `type_id`, `namespace_uri`, `parent_id`, `is_composition`
+- `VQT` — `value`, `quality`, `timestamp`
+- `LastKnownValue` — `element_id`, `data` (list of VQT), `children`
+- `ValueChange` — `element_id`, `data` (list of VQT), `children`
+- `Subscription` — `subscription_id`, `created`, `is_streaming`, `queued_updates`, `objects`
+
+### Errors
+
+All errors inherit from `i3x.I3XError`:
+
+- `ConnectionError` — Failed to connect
+- `AuthenticationError` — Auth rejected (401/403)
+- `NotFoundError` — Resource not found (404)
+- `ServerError` — Server error (5xx)
+- `TimeoutError` — Request timed out
+- `SubscriptionError` — Subscription operation failed
+- `StreamError` — SSE streaming error
+
+## License
+
+MIT

i3x_client-0.1.0/README.md

@@ -0,0 +1,152 @@
+# i3x-client
+
+Python client library for I3X CMIP servers.
+
+## Installation
+
+```bash
+pip install i3x-client
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import i3x
+
+# Connect to a CMIP server
+client = i3x.Client("http://localhost:8080")
+client.connect()
+
+# Explore the data model
+namespaces = client.get_namespaces()
+object_types = client.get_object_types()
+objects = client.get_objects(type_id="some-type")
+
+# Read values
+value = client.get_value("element-id-1")
+print(value.data[0].value, value.data[0].quality)
+
+# Read historical values
+history = client.get_history("element-id-1", start_time="2026-01-01T00:00:00Z")
+
+# Write values
+client.update_value("element-id-1", {"temperature": 72.5})
+
+# Disconnect
+client.disconnect()
+```
+
+### Context Manager
+
+```python
+with i3x.Client("http://localhost:8080") as client:
+    namespaces = client.get_namespaces()
+```
+
+### Subscriptions
+
+```python
+client = i3x.Client("http://localhost:8080")
+client.on_value_change = lambda client, change: print(f"{change.element_id}: {change.data}")
+client.connect()
+
+# Subscribe to value changes (creates subscription + registers + starts SSE stream)
+sub = client.subscribe(["element-id-1", "element-id-2"])
+
+# ... on_value_change fires automatically when values change ...
+
+# Unsubscribe when done
+client.unsubscribe(sub)
+client.disconnect()
+```
+
+### Authentication
+
+```python
+client = i3x.Client("http://localhost:8080", auth=("api-key", "secret"))
+```
+
+## API Reference
+
+### Client Methods
+
+#### Connection
+- `connect()` — Connect to the server
+- `disconnect()` — Disconnect and stop all subscriptions
+- `is_connected` — Property indicating connection state
+
+#### Callbacks
+- `on_connect(client)` — Called after successful connection
+- `on_disconnect(client)` — Called after disconnection
+- `on_value_change(client, change)` — Called when a subscribed value changes
+- `on_subscribe(client, subscription)` — Called after a subscription is created
+- `on_error(client, error)` — Called on stream/subscription errors
+
+#### Exploration
+- `get_namespaces()` — List all namespaces
+- `get_object_types(namespace_uri=None)` — List object types
+- `query_object_types(element_ids)` — Query types by ID
+- `get_relationship_types(namespace_uri=None)` — List relationship types
+- `query_relationship_types(element_ids)` — Query relationship types by ID
+- `get_objects(type_id=None, include_metadata=False)` — List object instances
+- `get_object(element_id)` — Get a single object
+- `list_objects(element_ids)` — Get multiple objects by ID
+- `get_related_objects(element_ids, relationship_type)` — Get related objects
+
+#### Values
+- `get_value(element_id, max_depth=1)` — Get last known value
+- `get_values(element_ids, max_depth=1)` — Get multiple last known values
+- `get_history(element_id, start_time=None, end_time=None, max_depth=1)` — Get historical values
+
+#### Updates
+- `update_value(element_id, value)` — Update an element's value
+- `update_history(element_id, value)` — Update historical values
+
+#### Subscriptions (High-Level)
+- `subscribe(element_ids, max_depth=0)` — Create subscription + register + start stream
+- `unsubscribe(subscription)` — Stop stream and delete subscription
+- `sync_subscription(subscription)` — Poll queued updates
+
+#### Subscriptions (Low-Level)
+- `create_subscription()` — Create an empty subscription
+- `register_items(subscription_id, element_ids, max_depth=0)` — Register items
+- `unregister_items(subscription_id, element_ids)` — Unregister items
+- `get_subscriptions()` — List all subscriptions
+- `get_subscription(subscription_id)` — Get subscription details
+- `start_stream(subscription_id)` — Start SSE for an existing subscription
+- `stop_stream(subscription_id)` — Stop SSE without deleting subscription
+
+### Models
+
+All models are frozen dataclasses with `from_dict()` classmethods.
+
+- `Namespace` — `uri`, `display_name`
+- `ObjectType` — `element_id`, `display_name`, `namespace_uri`, `schema`
+- `RelationshipType` — `element_id`, `display_name`, `namespace_uri`, `reverse_of`
+- `ObjectInstance` — `element_id`, `display_name`, `type_id`, `namespace_uri`, `parent_id`, `is_composition`
+- `VQT` — `value`, `quality`, `timestamp`
+- `LastKnownValue` — `element_id`, `data` (list of VQT), `children`
+- `ValueChange` — `element_id`, `data` (list of VQT), `children`
+- `Subscription` — `subscription_id`, `created`, `is_streaming`, `queued_updates`, `objects`
+
+### Errors
+
+All errors inherit from `i3x.I3XError`:
+
+- `ConnectionError` — Failed to connect
+- `AuthenticationError` — Auth rejected (401/403)
+- `NotFoundError` — Resource not found (404)
+- `ServerError` — Server error (5xx)
+- `TimeoutError` — Request timed out
+- `SubscriptionError` — Subscription operation failed
+- `StreamError` — SSE streaming error
+
+## License
+
+MIT

i3x_client-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "i3x-client"
+version = "0.1.0"
+description = "Python client library for I3X CMIP servers"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "I3X Working Group" },
+]
+keywords = ["i3x", "cmip", "iot", "building-automation", "client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "httpx>=0.24.0",
+    "httpx-sse>=0.4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "respx>=0.20.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/i3x/i3x-python"
+Documentation = "https://github.com/i3x/i3x-python#readme"
+Issues = "https://github.com/i3x/i3x-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/i3x"]

i3x_client-0.1.0/src/i3x/__init__.py

@@ -0,0 +1,48 @@
+"""i3x - Python client library for I3X CMIP servers."""
+
+__version__ = "0.1.0"
+
+from .client import Client
+from .errors import (
+    AuthenticationError,
+    ConnectionError,
+    I3XError,
+    NotFoundError,
+    ServerError,
+    StreamError,
+    SubscriptionError,
+    TimeoutError,
+)
+from .models import (
+    LastKnownValue,
+    Namespace,
+    ObjectInstance,
+    ObjectType,
+    RelationshipType,
+    Subscription,
+    ValueChange,
+    VQT,
+)
+
+__all__ = [
+    "__version__",
+    "Client",
+    # Errors
+    "I3XError",
+    "ConnectionError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ServerError",
+    "TimeoutError",
+    "SubscriptionError",
+    "StreamError",
+    # Models
+    "Namespace",
+    "ObjectType",
+    "RelationshipType",
+    "ObjectInstance",
+    "LastKnownValue",
+    "ValueChange",
+    "Subscription",
+    "VQT",
+]

i3x_client-0.1.0/src/i3x/_sse.py

@@ -0,0 +1,122 @@
+"""Internal SSE stream reader running in a background daemon thread."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from typing import TYPE_CHECKING, Any, Callable
+
+import httpx
+from httpx_sse import connect_sse
+
+from . import errors
+from .models import ValueChange
+
+if TYPE_CHECKING:
+    from ._transport import Transport
+
+logger = logging.getLogger("i3x.sse")
+
+
+class SSEStream:
+    """Manages an SSE connection to a subscription stream in a background thread."""
+
+    def __init__(
+        self,
+        transport: Transport,
+        subscription_id: str,
+        on_event: Callable[[list[ValueChange]], None],
+        on_error: Callable[[Exception], None],
+    ):
+        self._transport = transport
+        self._subscription_id = subscription_id
+        self._on_event = on_event
+        self._on_error = on_error
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    @property
+    def is_running(self) -> bool:
+        return self._thread is not None and self._thread.is_alive()
+
+    def start(self) -> None:
+        """Start the background SSE listener thread."""
+        if self.is_running:
+            return
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._run,
+            name=f"i3x-sse-{self._subscription_id}",
+            daemon=True,
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Signal the background thread to stop and wait for it."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=5.0)
+            self._thread = None
+
+    def _run(self) -> None:
+        """Background thread entry point."""
+        path = f"/subscriptions/{self._subscription_id}/stream"
+        try:
+            response = self._transport.stream_get(path)
+        except Exception as exc:
+            self._on_error(errors.StreamError(f"Failed to open SSE stream: {exc}"))
+            return
+
+        try:
+            self._read_events(response)
+        except Exception as exc:
+            if not self._stop_event.is_set():
+                self._on_error(errors.StreamError(f"SSE stream error: {exc}"))
+        finally:
+            response.close()
+
+    def _read_events(self, response: httpx.Response) -> None:
+        """Read SSE events from the response stream."""
+        from httpx_sse import SSEError
+
+        # Read the raw byte stream and parse SSE events manually
+        # since we already have a streaming response
+        buffer = ""
+        for chunk in response.stream.iter_text():
+            if self._stop_event.is_set():
+                return
+            buffer += chunk
+            while "\n\n" in buffer:
+                event_text, buffer = buffer.split("\n\n", 1)
+                self._process_event_text(event_text)
+
+    def _process_event_text(self, event_text: str) -> None:
+        """Parse and process a single SSE event."""
+        data_lines = []
+        for line in event_text.split("\n"):
+            if line.startswith("data:"):
+                data_lines.append(line[5:].strip())
+            elif line.startswith("data: "):
+                data_lines.append(line[6:])
+
+        if not data_lines:
+            return
+
+        data_str = "\n".join(data_lines)
+        try:
+            parsed = json.loads(data_str)
+        except json.JSONDecodeError:
+            logger.warning("Failed to parse SSE event data: %s", data_str)
+            return
+
+        # The stream sends an array of update dicts or a single update dict
+        if isinstance(parsed, list):
+            for item in parsed:
+                changes = ValueChange.from_stream_event(item)
+                if changes:
+                    self._on_event(changes)
+        elif isinstance(parsed, dict):
+            changes = ValueChange.from_stream_event(parsed)
+            if changes:
+                self._on_event(changes)

i3x_client-0.1.0/src/i3x/_subscription.py

@@ -0,0 +1,58 @@
+"""Internal subscription lifecycle tracker."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Callable
+
+from .models import Subscription, ValueChange
+from ._sse import SSEStream
+
+if TYPE_CHECKING:
+    from ._transport import Transport
+
+logger = logging.getLogger("i3x.subscription")
+
+
+class SubscriptionManager:
+    """Tracks active subscriptions and their SSE streams."""
+
+    def __init__(
+        self,
+        transport: Transport,
+        on_event: Callable[[list[ValueChange]], None],
+        on_error: Callable[[Exception], None],
+    ):
+        self._transport = transport
+        self._on_event = on_event
+        self._on_error = on_error
+        self._streams: dict[str, SSEStream] = {}
+
+    def add(self, subscription_id: str) -> None:
+        """Start an SSE stream for a subscription."""
+        if subscription_id in self._streams:
+            return
+        stream = SSEStream(
+            transport=self._transport,
+            subscription_id=subscription_id,
+            on_event=self._on_event,
+            on_error=self._on_error,
+        )
+        self._streams[subscription_id] = stream
+        stream.start()
+
+    def remove(self, subscription_id: str) -> None:
+        """Stop and remove the SSE stream for a subscription."""
+        stream = self._streams.pop(subscription_id, None)
+        if stream is not None:
+            stream.stop()
+
+    def stop_all(self) -> None:
+        """Stop all active SSE streams."""
+        for stream in self._streams.values():
+            stream.stop()
+        self._streams.clear()
+
+    def is_streaming(self, subscription_id: str) -> bool:
+        stream = self._streams.get(subscription_id)
+        return stream is not None and stream.is_running