cremalink 0.1.0b5__py3-none-any.whl

cremalink/transports/local/transport.py

@@ -0,0 +1,164 @@
+"""
+This module provides the `LocalTransport` class, which handles communication
+with a coffee machine over the local network (LAN) via a proxy server.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+from datetime import datetime
+
+import requests
+
+from cremalink.parsing.monitor.decode import build_monitor_snapshot
+from cremalink.parsing.properties.decode import PropertiesSnapshot
+from cremalink.transports.base import DeviceTransport
+
+
+class LocalTransport(DeviceTransport):
+    """
+    A transport for communicating with a device on the local network.
+
+    This transport does not connect to the device directly. Instead, it sends
+    requests to a local proxy server (`cremalink.local_server`), which then
+    forwards them to the coffee machine. This architecture simplifies direct
+    device communication and authentication.
+    """
+
+    def __init__(
+        self,
+        dsn: str,
+        lan_key: str,
+        device_ip: Optional[str],
+        server_host: str = "127.0.0.1",
+        server_port: int = 10280,
+        device_scheme: str = "http",
+        auto_configure: bool = False,
+        command_map: Optional[dict[str, Any]] = None,
+        property_map: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """
+        Initializes the LocalTransport.
+
+        Args:
+            dsn: The Device Serial Number.
+            lan_key: The key for LAN authentication.
+            device_ip: The IP address of the coffee machine.
+            server_host: The hostname or IP of the local proxy server.
+            server_port: The port of the local proxy server.
+            device_scheme: The protocol to use for device communication (e.g., 'http').
+            auto_configure: If True, automatically configures the server on init.
+            command_map: A pre-loaded map of device commands.
+            property_map: A pre-loaded map of device properties.
+        """
+        self.dsn = dsn
+        self.lan_key = lan_key
+        self.device_ip = device_ip
+        self.device_scheme = device_scheme
+        self.server_base_url = f"http://{server_host}:{server_port}"
+        self._configured = False
+        self.command_map = command_map or {}
+        self.property_map = property_map or {}
+        self._auto_configure = auto_configure
+        if auto_configure:
+            self.configure()
+
+    # ---- helpers ----
+    def _post_server(self, path: str, body: dict, timeout: int = 10) -> requests.Response:
+        """Helper for making POST requests to the local proxy server."""
+        return requests.post(
+            url=f"{self.server_base_url}{path}",
+            headers={"Content-Type": "application/json"},
+            json=body,
+            timeout=timeout,
+        )
+
+    def _get_server(self, path: str, timeout: int = 10) -> requests.Response:
+        """Helper for making GET requests to the local proxy server."""
+        return requests.get(f"{self.server_base_url}{path}", timeout=timeout)
+
+    # ---- DeviceTransport Implementation ----
+    def configure(self) -> None:
+        """
+        Configures the local proxy server with the device's connection details.
+        This must be called before other methods can be used.
+        """
+        monitor_prop_name = self.property_map.get("monitor", "d302_monitor")
+        payload = {
+            "dsn": self.dsn,
+            "device_ip": self.device_ip,
+            "lan_key": self.lan_key,
+            "device_scheme": self.device_scheme,
+            "monitor_property_name": monitor_prop_name,
+        }
+        try:
+            resp = self._post_server("/configure", payload)
+        except requests.RequestException as exc:
+            raise ConnectionError(
+                f"Could not reach local server at {self.server_base_url} during configure. "
+                f"Start the server (python -m cremalink.local_server) or adjust server_host/server_port. "
+                f"Original error: {exc}"
+            ) from exc
+        if resp.status_code not in (200, 201):
+            raise ValueError(f"Failed to configure server: {resp.status_code} {resp.text}")
+        self._configured = True
+
+    def send_command(self, command: str) -> dict[str, Any]:
+        """Sends a command to the device via the local proxy server."""
+        if not self._configured:
+            self.configure()
+        resp = self._post_server("/command", {"command": command})
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_properties(self) -> PropertiesSnapshot:
+        """Retrieves all device properties from the local proxy server."""
+        resp = self._get_server("/get_properties")
+        resp.raise_for_status()
+        payload = resp.json()
+        received = payload.get("received_at")
+        received_dt = datetime.fromtimestamp(received) if received else None
+        return PropertiesSnapshot(raw=payload.get("properties", payload), received_at=received_dt)
+
+    def get_property(self, name: str) -> Any:
+        """Retrieves a single property value from the local proxy server."""
+        # First, try to get it from the bulk properties snapshot
+        snapshot = self.get_properties()
+        value = snapshot.get(name)
+        if value is None:
+            # If not found, request it individually
+            resp = self._get_server(f"/properties/{name}")
+            resp.raise_for_status()
+            return resp.json().get("value")
+        return value
+
+    def get_monitor(self) -> Any:
+        """Retrieves and parses the device's monitoring data."""
+        resp = self._get_server("/get_monitor")
+        resp.raise_for_status()
+        try:
+            payload = resp.json()
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Failed to parse monitor payload: {resp.text}") from exc
+        return build_monitor_snapshot(payload, source="local", device_id=self.dsn)
+
+    def refresh_monitor(self) -> None:
+        """Requests a refresh of the monitoring data via the local proxy server."""
+        resp = self._get_server("/refresh_monitor")
+        resp.raise_for_status()
+
+    def health(self) -> str:
+        """Checks the health of the local proxy server."""
+        return self._get_server("/health").text
+
+    def set_mappings(self, command_map: dict[str, Any], property_map: dict[str, Any]) -> None:
+        """
+        Sets the command and property maps and re-configures the server if needed.
+        If the name of the monitoring property changes, the server is reconfigured.
+        """
+        previous_monitor = self.property_map.get("monitor", "d302_monitor")
+        self.command_map = command_map
+        self.property_map = property_map
+        updated_monitor = self.property_map.get("monitor", "d302_monitor")
+        if self._auto_configure and (not self._configured or previous_monitor != updated_monitor):
+            self.configure()

cremalink-0.1.0b5.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: cremalink
+Version: 0.1.0b5
+Summary: Python library and local API server for monitoring and controlling IoT coffee machines.
+Author-email: Midian Tekle Elfu <developer@midian.tekleelfu.de>
+Maintainer-email: Midian Tekle Elfu <developer@midian.tekleelfu.de>
+License-Expression: AGPL-3.0-or-later
+Project-URL: homepage, https://github.com/miditkl/cremalink
+Project-URL: source, https://github.com/miditkl/cremalink.git
+Project-URL: issues, https://github.com/miditkl/cremalink/issues
+Project-URL: download, https://github.com/miditkl/cremalink/archive/refs/heads/main.zip
+Project-URL: funding, https://github.com/sponsors/miditkl
+Keywords: Local Control,Cloud Control,Coffee Machine,IoT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests==2.32.5
+Requires-Dist: pycryptodome==3.23.0
+Requires-Dist: fastapi==0.128.0
+Requires-Dist: uvicorn==0.40.0
+Requires-Dist: httpx==0.28.1
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: pydantic-settings==2.12.0
+Provides-Extra: dev
+Requires-Dist: cremalink[test]; extra == "dev"
+Requires-Dist: cremalink[docs]; extra == "dev"
+Requires-Dist: ipykernel==7.1.0; extra == "dev"
+Requires-Dist: notebook==7.5.1; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest==9.0.2; extra == "test"
+Requires-Dist: pytest-asyncio==1.3.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx==8.2.3; extra == "docs"
+Requires-Dist: sphinxcontrib-websupport==2.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme==3.0.2; extra == "docs"
+Dynamic: license-file
+
+# ☕ Cremalink
+
+**A high-performance Python library and local API server for monitoring and controlling IoT coffee machines.**
+
+[![PyPI version](https://img.shields.io/pypi/v/cremalink.svg?style=for-the-badge&color=blue)](https://pypi.org/project/cremalink/)
+[![Python Version](https://img.shields.io/pypi/pyversions/cremalink.svg?style=for-the-badge&color=FFE169&labelColor=3776AB)](https://pypi.org/project/cremalink/)
+[![License](https://img.shields.io/github/license/miditkl/cremalink?style=for-the-badge&color=success)](LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/cremalink.svg?style=for-the-badge&color=orange)](https://pypi.org/project/cremalink/)
+[![Source Code](https://img.shields.io/badge/Source-GitHub-black?style=for-the-badge&logo=github)](https://github.com/miditkl/cremalink)
+
+---
+
+## ✨ Overview
+
+Cremalink provides a unified interface to interact with smart coffee machines via **Local LAN control** or **Cloud API**. It allows for real-time state monitoring and precise command execution.
+
+> [!TIP]
+> For detailed guides, advanced configuration, and developer deep-dives, please visit our **[Project Wiki](https://github.com/miditkl/cremalink/wiki)**.
+
+---
+
+## 🚀 Installation
+
+Install the package via `pip` (Cremalink requires **Python 3.13+**):
+
+```bash
+pip install cremalink
+
+```
+
+### Optional Dependencies
+
+To include tools for development or testing:
+
+```bash
+pip install "cremalink[dev]"   # For notebooks and kernel support
+pip install "cremalink[test]"  # For running pytest suites
+
+```
+
+---
+
+## 🛠 Usage
+
+### Integrated API Server
+
+Cremalink includes a FastAPI-based server for headless environments:
+
+```bash
+# Start the server (default port 10800)
+cremalink-server --ip 0.0.0.0 --port 10800
+```
+> More information: [Local Server Setup](https://github.com/miditkl/cremalink/wiki/3.-Local-Server-Setup)
+
+### Python API (Local Control)
+
+Connect to your machine directly via your local network for the lowest latency
+
+> More information: [Local Device]()
+
+---
+
+## 🛠 Development
+
+### Testing
+
+Run the comprehensive test suite using `pytest`:
+
+```bash
+pytest tests/
+
+```
+
+### Contributing
+
+Contributions are welcome! If you have a machine profile not yet supported, please check the [Wiki: 5. Adding Custom Devices](https://github.com/miditkl/cremalink/wiki/) on how to add new `.json` device definitions.
+
+Currently supported devices:
+
+- `De'Longhi PrimaDonna Soul (AY008ESP1)`
+---
+
+## 📄 License
+
+Distributed under the **AGPL-3.0-or-later** License. See `LICENSE` for more information.
+
+---
+
+*Developed by [Midian Tekle Elfu](mailto:developer@midian.tekleelfu.de). Supported by the community.*

cremalink-0.1.0b5.dist-info/RECORD

@@ -0,0 +1,47 @@
+cremalink/__init__.py,sha256=2W2cTIvMMkpq3x8kqtuawcEgjL4cX19qhBtTcjWgC4M,1080
+cremalink/local_server.py,sha256=KfokRoehbzOxFLILnojvTVh_VUR_KQ3wDWxm2-NY3FM,2279
+cremalink/clients/__init__.py,sha256=vncISOmt3xy-T4ouOBwoCvp546QNIdGXFUErmNDltHw,267
+cremalink/clients/cloud.py,sha256=yQBJHpLJ2CAUaRDrNZridK7E13j_RJc9FrCSKjA9ois,4793
+cremalink/core/__init__.py,sha256=ySQEhr2Le72t9opwaXarLf_m5EwRuMM9_CxXNxabWxU,128
+cremalink/core/binary.py,sha256=ue0tIM2sZrKUYncYYXu3kjc-HShBe2EDXBz6MOh3lOU,3003
+cremalink/crypto/__init__.py,sha256=15-cM__grOMPB1B2sQmUN0IZG4k4tcINyw6L0GXg7-I,3788
+cremalink/devices/AY008ESP1.json,sha256=e7vIetxeMsfdmgWCYxa2UQpJHqFWkX2xLIZpNKuSsIY,2629
+cremalink/devices/__init__.py,sha256=T4Wsw0QQug6z1cQE85G7BASTObde_8kNWHCW2poMZPs,3528
+cremalink/domain/__init__.py,sha256=2U7XWBTBQTZ2DfL2ekYY4ct9gk2g4apqR6HW3zwUVqo,479
+cremalink/domain/device.py,sha256=fTCswGb853pTSy2gaFZVJvjBRy9nQrBzxI5MkeqP9MM,9047
+cremalink/domain/factory.py,sha256=h4AO-I_S0cAy8LwLPrjeooFFBT_sbjB_bLN9iq2b5GM,3467
+cremalink/local_server_app/__init__.py,sha256=02AKAXMDZEayZrvN9jRiyaBRiOYppCLx4oljbwmN0qQ,605
+cremalink/local_server_app/api.py,sha256=S9p-_7htlBSic99ym1wgdsaCX0NTVxkDjX5E0RjzABQ,11703
+cremalink/local_server_app/config.py,sha256=v_btFsV2D3FtUNuawUUH0Xv3CBc4zpz_yOwHCTGZabE,3779
+cremalink/local_server_app/device_adapter.py,sha256=Dbdse8ENcKYAnHU1zP42IjLXDOl3OqeP7hu48g-IE-s,3488
+cremalink/local_server_app/jobs.py,sha256=nxMIDXSg-0fLSZPHMQVT-UKkocxiLFD7CIY6uwsK1T8,4051
+cremalink/local_server_app/logging.py,sha256=w04NNNwXvIfTr4rUXJWEmbtw8OvsFFrHksk0qPk6zRc,3499
+cremalink/local_server_app/models.py,sha256=ibUmbLLYm7s5ddMtsgItyYVpSeYtjSy9ZHZGzm_ekX8,2161
+cremalink/local_server_app/protocol.py,sha256=xdxhqDDSxMrEQSiXZ5ZEjzhBePmiXtIu9di5N2IeGwM,4772
+cremalink/local_server_app/state.py,sha256=HPhmZ7BtSo1AEfNfK6mWXz91oXBATfj3EwjA_HFpxLw,14652
+cremalink/parsing/__init__.py,sha256=DCrsPd9G94qfMfd-CMPfdqHvGdrYyaX97y3WCq8jVtA,223
+cremalink/parsing/monitor/__init__.py,sha256=Bsg68VQErYxHW7xX0PgSY97-6A7_yttGrbu2vW_H1hs,856
+cremalink/parsing/monitor/decode.py,sha256=JsX6S6pmLkV56PWPgpu1ZLabv73ept50ozknC5WW7Sk,2744
+cremalink/parsing/monitor/extractors.py,sha256=6EHdb32fBpzWc_kgRh-DcTUZ5E3MKikpse0SiZZ1LWc,2385
+cremalink/parsing/monitor/frame.py,sha256=xKDzW1-CWMXz5R1ZtDk6BlJoxM4FqS-mu6jfD_65kNU,4234
+cremalink/parsing/monitor/model.py,sha256=wNwVsHs8TucZpztnsN1ZEBsoFuad5cyv_D8CTDpF3Ow,1635
+cremalink/parsing/monitor/profile.py,sha256=zqaGVhhAQvsKmIddMM59p0bpcR4uzZc3PWvg5_r7Mck,5317
+cremalink/parsing/monitor/view.py,sha256=GSR-F9thscJERovP0qGAGAhl7tcz8Iq5DpvvBS9jhgM,7986
+cremalink/parsing/properties/__init__.py,sha256=Ux-F8aB9WDQeVQqBzfD7SGhiHT1upv5v_YaH27Utsgg,330
+cremalink/parsing/properties/decode.py,sha256=Y2tctsERRS-meqHtrptmw4_dyFWgxKZEQc6xRsr71C0,1965
+cremalink/resources/__init__.py,sha256=VYwjbH_pvUsaKCyzInMcdY4aChyxCwnzMrTHOS_Jhfc,344
+cremalink/resources/api_config.json,sha256=dyrKzA4W_zcENOQlt34OjMWhgkumPdZAJRKuPUPP0no,523
+cremalink/resources/api_config.py,sha256=iktoT7H_1mlgHVWyKL4BbDfkOFzUxUEsWWTBQr9bC70,987
+cremalink/resources/lang.json,sha256=g_NpYxPQ8C-lbRwBIb2CcN49KNzQtZZzcExzDAI4Kv0,5739
+cremalink/transports/__init__.py,sha256=HSViUbkcK6BE6H_TI2chJcaKzs_kAQ4PZ1pGWf8b5mc,267
+cremalink/transports/base.py,sha256=c9LWZHabdI1fQb7zN_DUTbnoYS6R2Pv-Jqaj9Usu_3A,2657
+cremalink/transports/cloud/__init__.py,sha256=o6JbkvGHq6d7bF6g5uyUJ_I4heyf3rmenE5bat22ibo,263
+cremalink/transports/cloud/transport.py,sha256=jMi4xFJjmAomF3Ke0XO7mXBvQqzFKYPw1IjRU1uXpA4,6509
+cremalink/transports/local/__init__.py,sha256=GvbBp8eynoKyV5m7q8y-_gAi2SUoC-4QIlRJ_WNo0lA,278
+cremalink/transports/local/transport.py,sha256=uSkBX1vyg2qX3W7mTg82g6UrRMAvkq6coVBJU8_nlhM,6845
+cremalink-0.1.0b5.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+cremalink-0.1.0b5.dist-info/METADATA,sha256=ReJVT_vNerBI9Mmep54H2kIauy0gSoMzItEw40gaaw0,4819
+cremalink-0.1.0b5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cremalink-0.1.0b5.dist-info/entry_points.txt,sha256=Cj-gxeRohv8ao9jp2oM4KiG8BQYyS_L1V1WfSMq6C_c,65
+cremalink-0.1.0b5.dist-info/top_level.txt,sha256=DwLIQZWW38UI0ixg6ZNSNvM0aSlyAhIUf7uE3sqJHOQ,10
+cremalink-0.1.0b5.dist-info/RECORD,,

cremalink-0.1.0b5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cremalink-0.1.0b5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cremalink-server = cremalink.local_server:main