python-oa3-client 0.1.0__py3-none-any.whl

openadr3_client/__init__.py

@@ -0,0 +1,41 @@
+from openadr3_client.base import BaseClient
+from openadr3_client.ven import VenClient, extract_topics
+from openadr3_client.bl import BlClient
+from openadr3_client.notifications import (
+    MqttChannel,
+    NotificationChannel,
+    WebhookChannel,
+)
+from openadr3_client.mqtt import MQTTConnection, MQTTMessage, normalize_broker_uri
+from openadr3_client.webhook import WebhookReceiver, WebhookMessage, detect_lan_ip
+from openadr3_client.discovery import (
+    DiscoveredVTN,
+    DiscoveryMode,
+    advertise_vtn,
+    discover_vtns,
+)
+
+__all__ = [
+    # Clients
+    "VenClient",
+    "BlClient",
+    "BaseClient",
+    # Discovery
+    "DiscoveredVTN",
+    "DiscoveryMode",
+    "discover_vtns",
+    "advertise_vtn",
+    # Notification channels
+    "MqttChannel",
+    "WebhookChannel",
+    "NotificationChannel",
+    # Low-level (still public)
+    "MQTTConnection",
+    "MQTTMessage",
+    "WebhookReceiver",
+    "WebhookMessage",
+    # Helpers
+    "extract_topics",
+    "normalize_broker_uri",
+    "detect_lan_ip",
+]

openadr3_client/base.py

@@ -0,0 +1,141 @@
+"""Base client with auth, lifecycle, and __getattr__ delegation to OpenADRClient."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any
+
+from openadr3.api import (
+    OpenADRClient,
+    create_bl_client,
+    create_ven_client,
+)
+from openadr3.auth import fetch_token
+
+from openadr3_client.discovery import DiscoveryMode, resolve_url
+
+log = logging.getLogger(__name__)
+
+
+class BaseClient:
+    """Lifecycle-managed OpenADR 3 client with __getattr__ delegation.
+
+    Any attribute not found on this class is forwarded to the underlying
+    OpenADRClient, eliminating the need for explicit delegation methods.
+    """
+
+    _client_type: str = "ven"
+
+    def __init__(
+        self,
+        url: str | None = None,
+        token: str | None = None,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        spec_version: str = "3.1.0",
+        spec_path: str | None = None,
+        validate: bool = False,
+        discovery: str | DiscoveryMode = "never",
+        discovery_timeout: float = 3.0,
+    ) -> None:
+        if not token and not (client_id and client_secret):
+            raise ValueError("Provide either token or both client_id and client_secret")
+
+        self.discovery_mode = DiscoveryMode(discovery)
+        self.discovery_timeout = discovery_timeout
+
+        if self.discovery_mode == DiscoveryMode.NEVER and not url:
+            raise ValueError("url is required when discovery='never'")
+        if self.discovery_mode == DiscoveryMode.LOCAL_WITH_FALLBACK and not url:
+            raise ValueError("url is required when discovery='local_with_fallback'")
+
+        self.url = url
+        self.token = token
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.spec_version = spec_version
+        self.spec_path = spec_path
+        self.validate = validate
+
+        self._resolved_url: str | None = None
+        self._api: OpenADRClient | None = None
+        self._lock = threading.Lock()
+
+    # -- Lifecycle --
+
+    def start(self) -> BaseClient:
+        """Start the client — creates the underlying OpenADRClient.
+
+        Resolves the VTN URL via mDNS discovery (if configured), then
+        fetches an auth token if needed, and creates the OpenADRClient.
+        """
+        if self._api:
+            log.info(
+                "%s already started: url=%s",
+                type(self).__name__, self._resolved_url,
+            )
+            return self
+
+        self._resolved_url = resolve_url(
+            self.discovery_mode, self.url, self.discovery_timeout,
+        )
+
+        if not self.token:
+            self.token = fetch_token(
+                base_url=self._resolved_url,
+                client_id=self.client_id,
+                client_secret=self.client_secret,
+            )
+            log.info("Token fetched via client credentials: client_id=%s", self.client_id)
+
+        create_fn = create_ven_client if self._client_type == "ven" else create_bl_client
+        self._api = create_fn(
+            base_url=self._resolved_url,
+            token=self.token,
+            spec_path=self.spec_path,
+            validate=self.validate,
+        )
+        log.info(
+            "%s started: type=%s url=%s",
+            type(self).__name__, self._client_type, self._resolved_url,
+        )
+        return self
+
+    def stop(self) -> BaseClient:
+        """Stop the client — close HTTP connection."""
+        if self._api:
+            self._api.close()
+            self._api = None
+        log.info("%s stopped", type(self).__name__)
+        return self
+
+    def __enter__(self):
+        return self.start()
+
+    def __exit__(self, *args: Any) -> None:
+        self.stop()
+
+    @property
+    def api(self) -> OpenADRClient:
+        """The underlying OpenADRClient. Raises if not started."""
+        if not self._api:
+            raise RuntimeError(
+                f"{type(self).__name__} not started. Call start() first."
+            )
+        return self._api
+
+    # -- __getattr__ delegation --
+
+    def __getattr__(self, name: str) -> Any:
+        """Forward unknown attributes to the underlying OpenADRClient."""
+        # Only delegate if _api exists and is set (avoid recursion during __init__)
+        api = self.__dict__.get("_api")
+        if api is not None:
+            try:
+                return getattr(api, name)
+            except AttributeError:
+                pass
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{name}'"
+        )

openadr3_client/bl.py

@@ -0,0 +1,18 @@
+"""BlClient — Business Logic client for program/event management."""
+
+from __future__ import annotations
+
+from openadr3_client.base import BaseClient
+
+
+class BlClient(BaseClient):
+    """OpenADR 3 Business Logic client.
+
+    Thin wrapper over BaseClient that sets client_type to "bl".
+    BL clients create and manage programs and events — no VEN
+    registration or notification concepts.
+
+    All OpenADRClient methods are available via __getattr__ delegation.
+    """
+
+    _client_type = "bl"

openadr3_client/discovery.py

@@ -0,0 +1,253 @@
+"""mDNS/DNS-SD discovery for OpenADR 3 VTNs.
+
+Browses for ``_openadr3._tcp.local.`` services via zeroconf and parses
+TXT records defined in the OpenADR 3.1.0 specification (section 4.1).
+
+The ``zeroconf`` package is lazily imported so that the core library
+works without it installed — add the ``[mdns]`` extra to pull it in.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+SERVICE_TYPE = "_openadr3._tcp.local."
+
+
+class DiscoveryMode(str, Enum):
+    """How the client should discover a VTN."""
+
+    NEVER = "never"
+    PREFER_LOCAL = "prefer_local"
+    LOCAL_WITH_FALLBACK = "local_with_fallback"
+    REQUIRE_LOCAL = "require_local"
+
+
+def _parse_txt_properties(properties: dict[bytes | str, bytes | str | None]) -> dict[str, str]:
+    """Convert zeroconf TXT record properties to ``{str: str}``."""
+    result: dict[str, str] = {}
+    for k, v in properties.items():
+        key = k.decode("utf-8") if isinstance(k, bytes) else k
+        if v is None:
+            result[key] = ""
+        elif isinstance(v, bytes):
+            result[key] = v.decode("utf-8")
+        else:
+            result[key] = str(v)
+    return result
+
+
+@dataclass(frozen=True)
+class DiscoveredVTN:
+    """A VTN discovered via mDNS/DNS-SD."""
+
+    name: str
+    host: str
+    port: int
+    base_path: str = "/"
+    version: str = ""
+    local_url: str = ""
+    program_names: str = ""
+    requires_auth: str = ""
+    openapi_url: str = ""
+
+    @property
+    def url(self) -> str:
+        """Resolved URL: ``local_url`` if set, else constructed from host/port/base_path."""
+        if self.local_url:
+            return self.local_url.rstrip("/")
+        scheme = "https" if self.port == 443 else "http"
+        base = self.base_path.rstrip("/") if self.base_path != "/" else ""
+        return f"{scheme}://{self.host}:{self.port}{base}"
+
+    @classmethod
+    def from_service_info(cls, info: Any) -> DiscoveredVTN:
+        """Build from a ``zeroconf.ServiceInfo`` object."""
+        props = _parse_txt_properties(info.properties or {})
+        # Prefer .server (the .local hostname) over parsed addresses
+        host = info.server.rstrip(".") if info.server else (
+            info.parsed_addresses()[0] if info.parsed_addresses() else "localhost"
+        )
+        return cls(
+            name=info.name,
+            host=host,
+            port=info.port,
+            base_path=props.get("base_path", "/"),
+            version=props.get("version", ""),
+            local_url=props.get("local_url", ""),
+            program_names=props.get("program_names", ""),
+            requires_auth=props.get("requires_auth", ""),
+            openapi_url=props.get("openapi_url", ""),
+        )
+
+
+def _import_zeroconf():
+    """Lazy-import zeroconf with a helpful error message."""
+    try:
+        import zeroconf  # noqa: F811
+        return zeroconf
+    except ImportError:
+        raise ImportError(
+            "zeroconf is required for mDNS discovery. "
+            "Install it with: pip install 'python-oa3-client[mdns]'"
+        ) from None
+
+
+def discover_vtns(timeout: float = 3.0) -> list[DiscoveredVTN]:
+    """Browse for OpenADR 3 VTNs via mDNS.
+
+    Blocks for *timeout* seconds while collecting service announcements,
+    then returns all discovered VTNs.
+    """
+    zc_mod = _import_zeroconf()
+    Zeroconf = zc_mod.Zeroconf
+    ServiceBrowser = zc_mod.ServiceBrowser
+
+    found: list[DiscoveredVTN] = []
+    event = threading.Event()
+
+    class Listener:
+        def add_service(self, zc: Any, type_: str, name: str) -> None:
+            info = zc.get_service_info(type_, name)
+            if info:
+                vtn = DiscoveredVTN.from_service_info(info)
+                found.append(vtn)
+                log.info("Discovered VTN: %s at %s", vtn.name, vtn.url)
+
+        def remove_service(self, zc: Any, type_: str, name: str) -> None:
+            pass
+
+        def update_service(self, zc: Any, type_: str, name: str) -> None:
+            pass
+
+    zc = Zeroconf()
+    try:
+        ServiceBrowser(zc, SERVICE_TYPE, Listener())
+        event.wait(timeout)
+    finally:
+        zc.close()
+
+    return found
+
+
+def resolve_url(
+    mode: DiscoveryMode | str,
+    configured_url: str | None,
+    timeout: float = 3.0,
+) -> str:
+    """Resolve the VTN URL based on discovery mode.
+
+    Called by ``BaseClient.start()`` to determine the final URL.
+    """
+    mode = DiscoveryMode(mode)
+
+    if mode == DiscoveryMode.NEVER:
+        if not configured_url:
+            raise ValueError("url is required when discovery='never'")
+        return configured_url
+
+    vtns = discover_vtns(timeout=timeout)
+    discovered_url = vtns[0].url if vtns else None
+
+    if mode == DiscoveryMode.REQUIRE_LOCAL:
+        if not discovered_url:
+            raise RuntimeError(
+                "discovery='require_local' but no VTN found via mDNS"
+            )
+        return discovered_url
+
+    if mode == DiscoveryMode.PREFER_LOCAL:
+        if discovered_url:
+            return discovered_url
+        if configured_url:
+            return configured_url
+        raise RuntimeError(
+            "discovery='prefer_local': no VTN found via mDNS and no url configured"
+        )
+
+    # LOCAL_WITH_FALLBACK
+    if discovered_url:
+        return discovered_url
+    # configured_url is guaranteed non-None by __init__ validation
+    return configured_url  # type: ignore[return-value]
+
+
+class _VTNAdvertiser:
+    """Context manager that registers an mDNS service for a VTN."""
+
+    def __init__(self, info: Any, zc: Any) -> None:
+        self._info = info
+        self._zc = zc
+
+    def close(self) -> None:
+        """Unregister the service and shut down zeroconf."""
+        self._zc.unregister_service(self._info)
+        self._zc.close()
+        log.info("mDNS service unregistered: %s", self._info.name)
+
+    def __enter__(self) -> _VTNAdvertiser:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+def advertise_vtn(
+    host: str,
+    port: int,
+    base_path: str = "/",
+    version: str = "3.1.0",
+    local_url: str = "",
+    program_names: str = "",
+    requires_auth: str = "false",
+    openapi_url: str = "",
+    name: str = "OpenADR3 VTN",
+) -> _VTNAdvertiser:
+    """Register an mDNS service advertising a VTN.
+
+    Returns a context manager / object with ``.close()`` to unregister.
+
+    Useful for testing discovery against a running VTN-RI without
+    modifying VTN-RI itself.
+    """
+    zc_mod = _import_zeroconf()
+    import socket
+
+    Zeroconf = zc_mod.Zeroconf
+    ServiceInfo = zc_mod.ServiceInfo
+
+    properties = {
+        "version": version,
+        "base_path": base_path,
+    }
+    if local_url:
+        properties["local_url"] = local_url
+    if program_names:
+        properties["program_names"] = program_names
+    if requires_auth:
+        properties["requires_auth"] = requires_auth
+    if openapi_url:
+        properties["openapi_url"] = openapi_url
+
+    info = ServiceInfo(
+        SERVICE_TYPE,
+        f"{name}.{SERVICE_TYPE}",
+        server=f"{host}.",
+        port=port,
+        properties=properties,
+        addresses=[socket.inet_aton(
+            "127.0.0.1" if host in ("localhost", "127.0.0.1") else host
+        )],
+    )
+
+    zc = Zeroconf()
+    zc.register_service(info)
+    log.info("mDNS service registered: %s on %s:%d", name, host, port)
+
+    return _VTNAdvertiser(info, zc)

openadr3_client/mqtt.py

@@ -0,0 +1,190 @@
+"""MQTT notification support for OpenADR 3 clients.
+
+Connects to an MQTT broker via ebus-mqtt-client and collects messages
+in a thread-safe list. Payloads that look like OpenADR notifications
+are automatically coerced into Notification models.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable
+from urllib.parse import urlparse
+
+from openadr3.entities import coerce_notification, is_notification
+
+log = logging.getLogger(__name__)
+
+
+def normalize_broker_uri(uri: str) -> tuple[str, int, bool]:
+    """Translate an MQTT URI into (host, port, use_tls).
+
+    Supports mqtt://, mqtts://, tcp://, ssl:// schemes.
+    Adds default ports (1883 for plain, 8883 for TLS) when omitted.
+    """
+    parsed = urlparse(uri)
+    scheme = parsed.scheme.lower()
+    host = parsed.hostname or "127.0.0.1"
+
+    if scheme in ("mqtts", "ssl"):
+        use_tls = True
+        port = parsed.port or 8883
+    else:
+        use_tls = False
+        port = parsed.port or 1883
+
+    return host, port, use_tls
+
+
+def _parse_payload(raw: bytes, topic: str) -> Any:
+    """Parse MQTT payload bytes as JSON, coercing notifications."""
+    try:
+        s = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return raw
+
+    try:
+        parsed = json.loads(s)
+    except (json.JSONDecodeError, ValueError):
+        return s
+
+    if isinstance(parsed, dict) and is_notification(parsed):
+        return coerce_notification(
+            parsed, {"openadr/channel": "mqtt", "openadr/topic": topic}
+        )
+    return parsed
+
+
+@dataclass
+class MQTTMessage:
+    """A received MQTT message."""
+
+    topic: str
+    payload: Any
+    time: float
+    raw_payload: bytes
+
+
+class MQTTConnection:
+    """MQTT connection with thread-safe message collection.
+
+    Wraps ebus-mqtt-client's MqttClient, adding:
+    - Message collection in a thread-safe list
+    - Notification payload coercion
+    - Await helpers for testing
+    """
+
+    def __init__(
+        self,
+        broker_url: str,
+        client_id: str | None = None,
+        on_message: Callable[[str, Any], None] | None = None,
+    ) -> None:
+        self.broker_url = broker_url
+        self.client_id = client_id or f"oa3-{id(self):x}"
+        self.on_message_callback = on_message
+        self._messages: list[MQTTMessage] = []
+        self._lock = threading.Lock()
+        self._client: MqttClient | None = None
+
+    def connect(self) -> None:
+        """Connect to the MQTT broker."""
+        try:
+            from ebus_mqtt_client import MqttClient
+        except ImportError:
+            raise ImportError(
+                "ebus-mqtt-client is required for MQTT support. "
+                "Install it with: pip install python-oa3-client[mqtt]"
+            )
+
+        host, port, use_tls = normalize_broker_uri(self.broker_url)
+        self._client = MqttClient(
+            client_id=self.client_id,
+            endpoint=host,
+            port=port,
+            use_tls=use_tls,
+            tls_insecure=True,
+        )
+        self._client.start()
+        log.info("MQTT connected: broker=%s client_id=%s", self.broker_url, self.client_id)
+
+    def disconnect(self) -> None:
+        """Disconnect from the MQTT broker."""
+        if self._client:
+            self._client.stop()
+            log.info("MQTT disconnected: broker=%s", self.broker_url)
+            self._client = None
+
+    def is_connected(self) -> bool:
+        return self._client.is_connected() if self._client else False
+
+    def subscribe(self, topics: list[str] | str) -> None:
+        """Subscribe to one or more MQTT topics."""
+        if not self._client:
+            raise RuntimeError("Not connected. Call connect() first.")
+        if isinstance(topics, str):
+            topics = [topics]
+        for topic in topics:
+            self._client.subscribe(topic, self._handle_message)
+        log.info("MQTT subscribed: topics=%s", topics)
+
+    def _handle_message(self, topic: str, payload: bytes) -> None:
+        """Internal callback — parse, collect, and dispatch."""
+        parsed = _parse_payload(payload, topic)
+        msg = MQTTMessage(
+            topic=topic,
+            payload=parsed,
+            time=time.time(),
+            raw_payload=payload,
+        )
+        with self._lock:
+            self._messages.append(msg)
+        log.debug("MQTT message: topic=%s", topic)
+        if self.on_message_callback:
+            self.on_message_callback(topic, parsed)
+
+    @property
+    def messages(self) -> list[MQTTMessage]:
+        """All collected messages (snapshot)."""
+        with self._lock:
+            return list(self._messages)
+
+    def messages_on_topic(self, topic: str) -> list[MQTTMessage]:
+        """Messages received on a specific topic."""
+        with self._lock:
+            return [m for m in self._messages if m.topic == topic]
+
+    def clear_messages(self) -> None:
+        """Clear collected messages."""
+        with self._lock:
+            self._messages.clear()
+
+    def await_messages(self, n: int, timeout: float = 5.0) -> list[MQTTMessage]:
+        """Wait until at least n messages collected, or timeout."""
+        deadline = time.time() + timeout
+        while True:
+            with self._lock:
+                if len(self._messages) >= n:
+                    return list(self._messages)
+            if time.time() >= deadline:
+                with self._lock:
+                    return list(self._messages)
+            time.sleep(0.05)
+
+    def await_messages_on_topic(
+        self, topic: str, n: int, timeout: float = 5.0
+    ) -> list[MQTTMessage]:
+        """Wait until at least n messages on a specific topic, or timeout."""
+        deadline = time.time() + timeout
+        while True:
+            msgs = self.messages_on_topic(topic)
+            if len(msgs) >= n:
+                return msgs
+            if time.time() >= deadline:
+                return msgs
+            time.sleep(0.05)