enapter 0.6.3__py3-none-any.whl → 0.12.1__py3-none-any.whl

enapter/__init__.py

@@ -1,6 +1,6 @@
-__version__ = "0.6.3"
+__version__ = "0.12.1"
 
-from . import async_, log, mdns, mqtt, types, vucm
+from . import async_, log, mdns, mqtt, http, standalone  # isort: skip
 
 __all__ = [
     "__version__",
@@ -8,6 +8,6 @@ __all__ = [
     "log",
     "mdns",
     "mqtt",
-    "types",
-    "vucm",
+    "http",
+    "standalone",
 ]

enapter/async_/__init__.py

@@ -1,7 +1,4 @@
 from .generator import generator
 from .routine import Routine
 
-__all__ = [
-    "generator",
-    "Routine",
-]
+__all__ = ["generator", "Routine"]

enapter/async_/generator.py

@@ -1,11 +1,14 @@
 import contextlib
 import functools
+from typing import AsyncContextManager, AsyncGenerator, Callable
 
 
-def generator(func):
+def generator(
+    func: Callable[..., AsyncGenerator],
+) -> Callable[..., AsyncContextManager[AsyncGenerator]]:
     @functools.wraps(func)
     @contextlib.asynccontextmanager
-    async def wrapper(*args, **kwargs):
+    async def wrapper(*args, **kwargs) -> AsyncGenerator[AsyncGenerator, None]:
         gen = func(*args, **kwargs)
         try:
             yield gen

enapter/async_/routine.py

@@ -1,69 +1,37 @@
 import abc
 import asyncio
 import contextlib
+from typing import Self
 
 
 class Routine(abc.ABC):
+
+    def __init__(self, task_group: asyncio.TaskGroup | None = None) -> None:
+        self._task_group = task_group
+        self._task: asyncio.Task | None = None
+
     @abc.abstractmethod
-    async def _run(self):
-        raise NotImplementedError  # pragma: no cover
+    async def _run(self) -> None:
+        pass  # pragma: no cover
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> Self:
         await self.start()
         return self
 
-    async def __aexit__(self, *_):
+    async def __aexit__(self, *_) -> None:
         await self.stop()
 
-    def task(self):
-        return self._task
-
-    async def start(self, cancel_parent_task_on_exception=True):
-        self._started = asyncio.Event()
-        self._stack = contextlib.AsyncExitStack()
-
-        self._parent_task = asyncio.current_task()
-        self._cancel_parent_task_on_exception = cancel_parent_task_on_exception
-
-        self._task = asyncio.create_task(self.__run())
-        wait_started_task = asyncio.create_task(self._started.wait())
-
-        done, _ = await asyncio.wait(
-            {self._task, wait_started_task},
-            return_when=asyncio.FIRST_COMPLETED,
-        )
-
-        if wait_started_task not in done:
-            wait_started_task.cancel()
-        try:
-            await wait_started_task
-        except asyncio.CancelledError:
-            pass
-
-        if self._task in done:
-            self._task.result()
-
-    async def stop(self):
-        self.cancel()
-        await self.join()
+    async def start(self) -> None:
+        if self._task is not None:
+            raise RuntimeError("already started")
+        if self._task_group is None:
+            self._task = asyncio.create_task(self._run())
+        else:
+            self._task = self._task_group.create_task(self._run())
 
-    def cancel(self):
+    async def stop(self) -> None:
+        if self._task is None:
+            raise RuntimeError("not started yet")
         self._task.cancel()
-
-    async def join(self):
-        if self._task.done():
-            self._task.result()
-        else:
+        with contextlib.suppress(asyncio.CancelledError):
             await self._task
-
-    async def __run(self):
-        try:
-            await self._run()
-        except asyncio.CancelledError:
-            pass
-        except:
-            if self._started.is_set() and self._cancel_parent_task_on_exception:
-                self._parent_task.cancel()
-            raise
-        finally:
-            await self._stack.aclose()

enapter/http/__init__.py

@@ -0,0 +1,3 @@
+from . import api
+
+__all__ = ["api"]

enapter/http/api/__init__.py

@@ -0,0 +1,5 @@
+from . import devices
+from .client import Client
+from .config import Config
+
+__all__ = ["Client", "Config", "devices"]

enapter/http/api/client.py

@@ -0,0 +1,31 @@
+from typing import Self
+
+import httpx
+
+from enapter.http.api import devices
+
+from .config import Config
+
+
+class Client:
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._client = self._new_client()
+
+    def _new_client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            headers={"X-Enapter-Auth-Token": self._config.token},
+            base_url=self._config.base_url,
+        )
+
+    async def __aenter__(self) -> Self:
+        await self._client.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self._client.__aexit__(*exc)
+
+    @property
+    def devices(self) -> devices.Client:
+        return devices.Client(client=self._client)

enapter/http/api/config.py

@@ -0,0 +1,23 @@
+import os
+from typing import MutableMapping, Self
+
+
+class Config:
+
+    @classmethod
+    def from_env(
+        cls, env: MutableMapping[str, str] = os.environ, namespace: str = "ENAPTER_"
+    ) -> Self:
+        prefix = namespace + "HTTP_API_"
+        return cls(
+            token=env[prefix + "TOKEN"],
+            base_url=env.get(prefix + "BASE_URL"),
+        )
+
+    def __init__(self, token: str, base_url: str | None = None) -> None:
+        if not token:
+            raise ValueError("token is missing")
+        self.token = token
+        if base_url is None:
+            base_url = "https://api.enapter.com"
+        self.base_url = base_url

enapter/http/api/devices/__init__.py

@@ -0,0 +1,21 @@
+from .authorized_role import AuthorizedRole
+from .client import Client
+from .communication_config import CommunicationConfig
+from .device import Device
+from .device_type import DeviceType
+from .mqtt_credentials import MQTTCredentials
+from .mqtt_protocol import MQTTProtocol
+from .mqtts_credentials import MQTTSCredentials
+from .time_sync_protocol import TimeSyncProtocol
+
+__all__ = [
+    "AuthorizedRole",
+    "Client",
+    "CommunicationConfig",
+    "Device",
+    "DeviceType",
+    "MQTTCredentials",
+    "MQTTProtocol",
+    "MQTTSCredentials",
+    "TimeSyncProtocol",
+]

enapter/http/api/devices/authorized_role.py

@@ -0,0 +1,11 @@
+import enum
+
+
+class AuthorizedRole(enum.Enum):
+
+    READONLY = "READONLY"
+    USER = "USER"
+    OWNER = "OWNER"
+    INSTALLER = "INSTALLER"
+    SYSTEM = "SYSTEM"
+    VENDOR = "VENDOR"

enapter/http/api/devices/client.py

@@ -0,0 +1,25 @@
+import httpx
+
+from .communication_config import CommunicationConfig
+from .device import Device
+from .mqtt_protocol import MQTTProtocol
+
+
+class Client:
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client = client
+
+    async def get(self, device_id: str) -> Device:
+        url = f"v3/devices/{device_id}"
+        response = await self._client.get(url)
+        response.raise_for_status()
+        return Device.from_dto(response.json()["device"])
+
+    async def generate_communication_config(
+        self, device_id: str, mqtt_protocol: MQTTProtocol
+    ) -> CommunicationConfig:
+        url = f"v3/devices/{device_id}/generate_config"
+        response = await self._client.post(url, json={"protocol": mqtt_protocol.value})
+        response.raise_for_status()
+        return CommunicationConfig.from_dto(response.json()["config"])

enapter/http/api/devices/communication_config.py

@@ -0,0 +1,45 @@
+import dataclasses
+from typing import Any, Self
+
+from .mqtt_credentials import MQTTCredentials
+from .mqtt_protocol import MQTTProtocol
+from .mqtts_credentials import MQTTSCredentials
+from .time_sync_protocol import TimeSyncProtocol
+
+
+@dataclasses.dataclass
+class CommunicationConfig:
+
+    mqtt_host: str
+    mqtt_port: int
+    mqtt_credentials: MQTTCredentials | MQTTSCredentials
+    mqtt_protocol: MQTTProtocol
+    time_sync_protocol: TimeSyncProtocol
+    time_sync_host: str
+    time_sync_port: int
+    hardware_id: str
+    channel_id: str
+
+    @classmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        mqtt_protocol = MQTTProtocol(dto["mqtt_protocol"])
+        mqtt_credentials: MQTTCredentials | MQTTSCredentials | None = None
+        match mqtt_protocol:
+            case MQTTProtocol.MQTT:
+                mqtt_credentials = MQTTCredentials.from_dto(dto["mqtt_credentials"])
+            case MQTTProtocol.MQTTS:
+                mqtt_credentials = MQTTSCredentials.from_dto(dto["mqtt_credentials"])
+            case _:
+                raise NotImplementedError(mqtt_protocol)
+        assert mqtt_credentials is not None
+        return cls(
+            mqtt_host=dto["mqtt_host"],
+            mqtt_port=int(dto["mqtt_port"]),
+            mqtt_credentials=mqtt_credentials,
+            mqtt_protocol=mqtt_protocol,
+            time_sync_protocol=TimeSyncProtocol(dto["time_sync_protocol"].upper()),
+            time_sync_host=dto["time_sync_host"],
+            time_sync_port=int(dto["time_sync_port"]),
+            hardware_id=dto["hardware_id"],
+            channel_id=dto["channel_id"],
+        )

enapter/http/api/devices/device.py

@@ -0,0 +1,32 @@
+import dataclasses
+import datetime
+from typing import Any, Self
+
+from .authorized_role import AuthorizedRole
+from .device_type import DeviceType
+
+
+@dataclasses.dataclass
+class Device:
+
+    id: str
+    blueprint_id: str
+    name: str
+    site_id: str
+    updated_at: datetime.datetime
+    slug: str
+    type: DeviceType
+    authorized_role: AuthorizedRole
+
+    @classmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        return cls(
+            id=dto["id"],
+            blueprint_id=dto["blueprint_id"],
+            name=dto["name"],
+            site_id=dto["site_id"],
+            updated_at=datetime.datetime.fromisoformat(dto["updated_at"]),
+            slug=dto["slug"],
+            type=DeviceType(dto["type"]),
+            authorized_role=AuthorizedRole(dto["authorized_role"]),
+        )

enapter/http/api/devices/device_type.py

@@ -0,0 +1,10 @@
+import enum
+
+
+class DeviceType(enum.Enum):
+
+    LUA = "LUA"
+    VIRTUAL_UCM = "VIRTUAL_UCM"
+    HARDWARE_UCM = "HARDWARE_UCM"
+    STANDALONE = "STANDALONE"
+    GATEWAY = "GATEWAY"

enapter/http/api/devices/mqtt_credentials.py

@@ -0,0 +1,13 @@
+import dataclasses
+from typing import Any, Self
+
+
+@dataclasses.dataclass
+class MQTTCredentials:
+
+    username: str
+    password: str
+
+    @classmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        return cls(username=dto["username"], password=dto["password"])

enapter/http/api/devices/mqtt_protocol.py

@@ -0,0 +1,7 @@
+import enum
+
+
+class MQTTProtocol(enum.Enum):
+
+    MQTT = "MQTT"
+    MQTTS = "MQTTS"

enapter/http/api/devices/mqtts_credentials.py

@@ -0,0 +1,18 @@
+import dataclasses
+from typing import Any, Self
+
+
+@dataclasses.dataclass
+class MQTTSCredentials:
+
+    private_key: str
+    certificate: str
+    ca_chain: str
+
+    @classmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        return cls(
+            private_key=dto["private_key"],
+            certificate=dto["certificate"],
+            ca_chain=dto["ca_chain"],
+        )

enapter/http/api/devices/time_sync_protocol.py

@@ -0,0 +1,6 @@
+import enum
+
+
+class TimeSyncProtocol(enum.Enum):
+
+    NTP = "NTP"

enapter/log/json_formatter.py

@@ -1,12 +1,22 @@
 import datetime
+import logging
+from typing import Any
 
-import json_log_formatter
+import json_log_formatter  # type: ignore
 
 
 class JSONFormatter(json_log_formatter.JSONFormatter):
-    def json_record(self, message, extra, record):
+
+    def json_record(
+        self, message: str, extra: dict[str, Any], record: logging.LogRecord
+    ) -> dict[str, Any]:
+        try:
+            del extra["taskName"]
+        except KeyError:
+            pass
+
         json_record = {
-            "time": datetime.datetime.utcnow().isoformat(),
+            "time": datetime.datetime.now(datetime.timezone.utc).isoformat(),
             "level": record.levelname[:4],
             "name": record.name,
             **extra,
@@ -22,5 +32,5 @@ class JSONFormatter(json_log_formatter.JSONFormatter):
 
         return json_record
 
-    def mutate_json_record(self, json_record):
+    def mutate_json_record(self, json_record: dict[str, Any]) -> dict[str, Any]:
         return json_record

enapter/mdns/resolver.py

@@ -1,39 +1,42 @@
 import logging
 
-import dns.asyncresolver
+import dns.asyncresolver  # type: ignore
 
 LOGGER = logging.getLogger(__name__)
 
 
 class Resolver:
-    def __init__(self):
+
+    def __init__(self) -> None:
         self._logger = LOGGER
         self._dns_resolver = self._new_dns_resolver()
         self._mdns_resolver = self._new_mdns_resolver()
 
-    async def resolve(self, host):
+    async def resolve(self, host: str) -> str:
         # TODO: Resolve concurrently.
         try:
-            return await self._resolve(self._dns_resolver, host)
+            ip = await self._resolve(self._dns_resolver, host)
+            self._logger.debug("%r resolved using DNS: %r", host, ip)
+            return ip
         except Exception as e:
             self._logger.debug(
-                "failed to resolve %r using DNS resolver, switching to mDNS: %r",
-                host,
-                e,
+                "switching to mDNS: failed to resolve %r using DNS: %r", host, e
             )
-            return await self._resolve(self._mdns_resolver, host)
+            ip = await self._resolve(self._mdns_resolver, host)
+            self._logger.info("%r resolved using mDNS: %r", host, ip)
+            return ip
 
-    async def _resolve(self, resolver, host):
+    async def _resolve(self, resolver: dns.asyncresolver.Resolver, host: str) -> str:
         answer = await resolver.resolve(host, "A")
         if not answer:
             raise ValueError(f"empty answer received: {host}")
 
         return answer[0].address
 
-    def _new_dns_resolver(self):
+    def _new_dns_resolver(self) -> dns.asyncresolver.Resolver:
         return dns.asyncresolver.Resolver(configure=True)
 
-    def _new_mdns_resolver(self):
+    def _new_mdns_resolver(self) -> dns.asyncresolver.Resolver:
         r = dns.asyncresolver.Resolver(configure=False)
         r.nameservers = ["224.0.0.251"]
         r.port = 5353

enapter/mqtt/__init__.py

@@ -1,14 +1,7 @@
 from .client import Client
-from .command import CommandRequest, CommandResponse, CommandState
-from .config import Config
-from .device_channel import DeviceChannel, DeviceLogSeverity
+from .errors import Error
+from .message import Message
 
-__all__ = [
-    "Client",
-    "CommandRequest",
-    "CommandResponse",
-    "CommandState",
-    "Config",
-    "DeviceChannel",
-    "DeviceLogSeverity",
-]
+from . import api  # isort: skip
+
+__all__ = ["Client", "Error", "Message", "api"]

enapter/mqtt/api/__init__.py

@@ -0,0 +1,6 @@
+from .client import Client
+from .config import Config, TLSConfig
+
+from . import device  # isort: skip
+
+__all__ = ["Client", "Config", "TLSConfig", "device"]

enapter/mqtt/api/client.py

@@ -0,0 +1,62 @@
+import asyncio
+import contextlib
+import ssl
+import tempfile
+from typing import Self
+
+from enapter import mqtt
+from enapter.mqtt.api import device
+
+from .config import Config
+
+
+class Client:
+
+    def __init__(self, config: Config, task_group: asyncio.TaskGroup | None) -> None:
+        self._config = config
+        self._client = self._new_client(task_group=task_group)
+
+    async def __aenter__(self) -> Self:
+        await self._client.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self._client.__aexit__(*exc)
+
+    def device_channel(self, hardware_id: str, channel_id: str) -> device.Channel:
+        return device.Channel(
+            client=self._client, hardware_id=hardware_id, channel_id=channel_id
+        )
+
+    def _new_client(self, task_group: asyncio.TaskGroup | None) -> mqtt.Client:
+        return mqtt.Client(
+            hostname=self._config.host,
+            port=self._config.port,
+            username=self._config.user,
+            password=self._config.password,
+            tls_context=self._new_tls_context(),
+            task_group=task_group,
+        )
+
+    def _new_tls_context(self) -> ssl.SSLContext | None:
+        if self._config.tls is None:
+            return None
+
+        ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+
+        ctx.verify_mode = ssl.CERT_REQUIRED
+        ctx.check_hostname = False
+        ctx.load_verify_locations(None, None, self._config.tls.ca_cert)
+
+        with contextlib.ExitStack() as stack:
+            certfile = stack.enter_context(tempfile.NamedTemporaryFile())
+            certfile.write(self._config.tls.cert.encode())
+            certfile.flush()
+
+            keyfile = stack.enter_context(tempfile.NamedTemporaryFile())
+            keyfile.write(self._config.tls.secret_key.encode())
+            keyfile.flush()
+
+            ctx.load_cert_chain(certfile.name, keyfile=keyfile.name)
+
+        return ctx

enapter/mqtt/api/config.py

@@ -0,0 +1,77 @@
+import os
+from typing import MutableMapping, Self
+
+
+class TLSConfig:
+
+    @classmethod
+    def from_env(
+        cls, env: MutableMapping[str, str] = os.environ, namespace: str = "ENAPTER_"
+    ) -> Self | None:
+        prefix = namespace + "MQTT_API_TLS_"
+
+        secret_key = env.get(prefix + "SECRET_KEY")
+        cert = env.get(prefix + "CERT")
+        ca_cert = env.get(prefix + "CA_CERT")
+
+        nothing_defined = {secret_key, cert, ca_cert} == {None}
+        if nothing_defined:
+            return None
+
+        if secret_key is None:
+            raise KeyError(prefix + "SECRET_KEY")
+        if cert is None:
+            raise KeyError(prefix + "CERT")
+        if ca_cert is None:
+            raise KeyError(prefix + "CA_CERT")
+
+        def pem(value: str) -> str:
+            return value.replace("\\n", "\n")
+
+        return cls(secret_key=pem(secret_key), cert=pem(cert), ca_cert=pem(ca_cert))
+
+    def __init__(self, secret_key: str, cert: str, ca_cert: str) -> None:
+        self.secret_key = secret_key
+        self.cert = cert
+        self.ca_cert = ca_cert
+
+
+class Config:
+
+    @classmethod
+    def from_env(
+        cls, env: MutableMapping[str, str] = os.environ, namespace: str = "ENAPTER_"
+    ) -> Self:
+        prefix = namespace + "MQTT_API_"
+        return cls(
+            host=env[prefix + "HOST"],
+            port=int(env[prefix + "PORT"]),
+            user=env.get(prefix + "USER", default=None),
+            password=env.get(prefix + "PASSWORD", default=None),
+            tls_config=TLSConfig.from_env(env, namespace=namespace),
+        )
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        user: str | None = None,
+        password: str | None = None,
+        tls_config: TLSConfig | None = None,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.user = user
+        self.password = password
+        self.tls_config = tls_config
+
+    @property
+    def tls(self) -> TLSConfig | None:
+        return self.tls_config
+
+    def __repr__(self) -> str:
+        return "mqtt.api.Config(host=%r, port=%r, tls=%r)" % (
+            self.host,
+            self.port,
+            self.tls is not None,
+        )