iobroker 0.1.0__tar.gz

iobroker-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Veroeffentlicht bei jedem GitHub-Release. Kein API-Token noetig:
+# PyPI vertraut diesem Workflow ueber OIDC (Trusted Publishing).
+# Voraussetzung: auf pypi.org unter Account -> Publishing ein
+# "pending publisher" mit genau diesen Werten anlegen --
+#   Project: iobroker | Owner: ioBroker
+#   Repository: iobroker-python | Workflow: publish.yml | Environment: pypi
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Der Token, mit dem sich der Workflow bei PyPI ausweist.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

iobroker-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

iobroker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bluefox <dogafox@gmail.com>
+
+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.

iobroker-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: iobroker
+Version: 0.1.0
+Summary: Python-SDK fuer ioBroker-Adapter -- spricht direkt das Redis-Wire-Protokoll der States- und Objects-Datenbank
+Project-URL: Homepage, https://github.com/ioBroker/iobroker-python
+Project-URL: Issues, https://github.com/ioBroker/iobroker-python/issues
+Author-email: bluefox <dogafox@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: adapter,home-automation,iobroker,redis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.10
+Requires-Dist: redis>=5.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: metrics
+Requires-Dist: psutil>=5.9; extra == 'metrics'
+Description-Content-Type: text/markdown
+
+# iobroker-python
+
+Python-SDK für ioBroker-Adapter. Spricht direkt das Redis-Wire-Protokoll der
+States- und Objects-Datenbank — ein Python-Prozess wird damit zum gleichrangigen
+Adapter neben jedem Node-Adapter, ohne Brücke und ohne Umweg.
+
+> **Status: 0.1.0, früher Entwurf.** Die Wire-Ebene ist gegen eine laufende
+> Installation verifiziert (js-controller 7.2.3, `jsonl`-Datenbanken). Die API
+> kann sich noch ändern.
+
+## Installation
+
+```bash
+pip install iobroker
+```
+
+## Ein Adapter in dreißig Zeilen
+
+```python
+from iobroker import Adapter, State
+
+class MyAdapter(Adapter):
+    async def on_ready(self):
+        await self.set_object_not_exists("temperature", {
+            "type": "state",
+            "common": {
+                "name": "Temperatur", "type": "number",
+                "role": "value.temperature", "unit": "°C",
+                "read": True, "write": False,
+            },
+        })
+        await self.subscribe_states("*")
+        await self.set_state("info.connection", True, ack=True)
+
+    async def on_state_change(self, id: str, state: State | None):
+        # ack=False heißt: jemand will etwas schalten.
+        if state and not state.ack:
+            self.log.info(f"Befehl auf {id}: {state.val}")
+
+    async def on_message(self, msg):
+        if msg.command == "ping":
+            await self.reply(msg, {"pong": True})
+
+MyAdapter("myadapter").run()
+```
+
+Ein lauffähiges Beispiel steht in [`examples/minimal_adapter.py`](https://github.com/ioBroker/iobroker-python/blob/main/examples/minimal_adapter.py).
+
+## Verbindungsdaten
+
+Der Adapter liest sie in dieser Reihenfolge:
+
+1. Umgebungsvariablen `IOB_STATES_HOST/PORT/DB/PASS/TYPE` und `IOB_OBJECTS_*`
+   — so wird der `py-controller` sie später durchreichen.
+2. `IOB_CONFIG` mit dem Pfad zur `iobroker.json`.
+3. Die üblichen Installationspfade.
+
+Instanznummer und Loglevel kommen aus `--instance` / `--loglevel` oder aus
+`IOB_INSTANCE` / `IOB_LOGLEVEL` — dieselben Argumente, die js-controller heute
+schon an Node-Adapter übergibt.
+
+## Was der eingebaute Server anders macht als Redis
+
+Im Standard-Setup redet man nicht mit echtem Redis, sondern mit dem
+Redis-Protokollserver in js-controller (Ports 9000 und 9001). Der weicht an
+mehreren Stellen ab. Alle folgenden Punkte sind an einer laufenden Installation
+am Draht nachgewiesen, nicht aus der Dokumentation abgeleitet — `tools/probe.py`
+prüft sie für die eigene Installation nach.
+
+| Abweichung | Auswirkung | Behandlung im SDK |
+|---|---|---|
+| **Kommandos müssen kleingeschrieben sein.** Der Server dispatcht ohne `toLowerCase()` (`db-base/redisHandler.js`), registriert seine Handler aber nur klein. ioredis sendet zufällig klein, redis-py sendet groß. | `GET …` → `-Error GET NOT SUPPORTED`, `get …` → `4`. Ohne Behandlung scheitert der erste Befehl. | `connection.py` hängt sich vor den Command-Packer von redis-py. Synchron über `_command_packer`, asynchron über `pack_command` — redis-py benutzt je nach Modus einen anderen Weg. |
+| **Kein `HELLO`.** redis-py verhandelt RESP3 beim Verbinden. | Verbindungsaufbau scheitert mit `HELLO NOT SUPPORTED`. | `protocol=2`, dazu `lib_name=None` gegen `CLIENT SETINFO`. |
+| **Kein `PING`** auf der States-DB. | Übliche Verbindungstests schlagen fehl. | Verbindungstest über `get meta.states.protocolVersion` — die Version muss ohnehin geprüft werden. |
+| **Kein `SCAN`** auf der States-DB. Die Objects-DB kann `scan`, `sscan`, `sadd`, `eval`. | Schlüssel müssen mit `keys` gesucht werden. | `DbConfig.is_builtin` unterscheidet; gegen echtes Redis ist `keys` blockierend und muss vermieden werden. |
+| **Pub/Sub liefert den Kanal ohne `io.`-Präfix.** Echtes Redis liefert ihn mit. | Wer stur das Präfix abschneidet, verstümmelt IDs. | Das SDK toleriert beides — genau wie der JS-Client. |
+| **Abgelaufene States melden sich anders.** Kein `__keyevent@0__:expired`; stattdessen kommt `null` auf dem State-Kanal selbst. | Gegen echtes Redis wäre ein zusätzliches Abo nötig. | `null` wird als „State weg“ an `on_state_change` gemeldet. |
+
+Dazu eine Eigenschaft, die kein Fehler, aber wichtig ist: **die Rechteprüfung
+sitzt im JS-Client, nicht im Datenbankserver.** Wer direkt auf der
+Redis-Verbindung sitzt, hat faktisch Adminrechte. Das gilt für Node-Adapter
+genauso — nur kommt bei Python fremder Code aus PyPI mit in den Prozess.
+
+## Capability-Probe
+
+```bash
+python tools/probe.py
+```
+
+(aus dem [Repository](https://github.com/ioBroker/iobroker-python), nicht im Wheel enthalten)
+
+Meldet für die eigene Installation, was die beiden Datenbanken können, und macht
+anschließend einen vollständigen Round-Trip: Objekt anlegen, State schreiben,
+Änderung empfangen. Räumt mit `--cleanup` wieder auf.
+
+## Lebenszyklus
+
+`alive`, `connected`, `uptime` und `memRss` schreibt der Adapter selbst über die
+States-DB — genauso wie ein Node-Adapter. Der Stopp läuft über den
+`sigKill`-State: setzt der Controller ihn auf `-1`, beendet sich der Adapter
+geordnet. Damit funktioniert das Anhalten auch unter Windows, wo es kein
+`SIGTERM` gibt.
+
+## Entwicklung
+
+```bash
+python -m venv .venv && .venv/Scripts/activate   # Windows
+pip install -e ".[dev]"
+python examples/minimal_adapter.py --instance 0
+```
+
+## Lizenz
+
+MIT

iobroker-0.1.0/README.md

@@ -0,0 +1,114 @@
+# iobroker-python
+
+Python-SDK für ioBroker-Adapter. Spricht direkt das Redis-Wire-Protokoll der
+States- und Objects-Datenbank — ein Python-Prozess wird damit zum gleichrangigen
+Adapter neben jedem Node-Adapter, ohne Brücke und ohne Umweg.
+
+> **Status: 0.1.0, früher Entwurf.** Die Wire-Ebene ist gegen eine laufende
+> Installation verifiziert (js-controller 7.2.3, `jsonl`-Datenbanken). Die API
+> kann sich noch ändern.
+
+## Installation
+
+```bash
+pip install iobroker
+```
+
+## Ein Adapter in dreißig Zeilen
+
+```python
+from iobroker import Adapter, State
+
+class MyAdapter(Adapter):
+    async def on_ready(self):
+        await self.set_object_not_exists("temperature", {
+            "type": "state",
+            "common": {
+                "name": "Temperatur", "type": "number",
+                "role": "value.temperature", "unit": "°C",
+                "read": True, "write": False,
+            },
+        })
+        await self.subscribe_states("*")
+        await self.set_state("info.connection", True, ack=True)
+
+    async def on_state_change(self, id: str, state: State | None):
+        # ack=False heißt: jemand will etwas schalten.
+        if state and not state.ack:
+            self.log.info(f"Befehl auf {id}: {state.val}")
+
+    async def on_message(self, msg):
+        if msg.command == "ping":
+            await self.reply(msg, {"pong": True})
+
+MyAdapter("myadapter").run()
+```
+
+Ein lauffähiges Beispiel steht in [`examples/minimal_adapter.py`](https://github.com/ioBroker/iobroker-python/blob/main/examples/minimal_adapter.py).
+
+## Verbindungsdaten
+
+Der Adapter liest sie in dieser Reihenfolge:
+
+1. Umgebungsvariablen `IOB_STATES_HOST/PORT/DB/PASS/TYPE` und `IOB_OBJECTS_*`
+   — so wird der `py-controller` sie später durchreichen.
+2. `IOB_CONFIG` mit dem Pfad zur `iobroker.json`.
+3. Die üblichen Installationspfade.
+
+Instanznummer und Loglevel kommen aus `--instance` / `--loglevel` oder aus
+`IOB_INSTANCE` / `IOB_LOGLEVEL` — dieselben Argumente, die js-controller heute
+schon an Node-Adapter übergibt.
+
+## Was der eingebaute Server anders macht als Redis
+
+Im Standard-Setup redet man nicht mit echtem Redis, sondern mit dem
+Redis-Protokollserver in js-controller (Ports 9000 und 9001). Der weicht an
+mehreren Stellen ab. Alle folgenden Punkte sind an einer laufenden Installation
+am Draht nachgewiesen, nicht aus der Dokumentation abgeleitet — `tools/probe.py`
+prüft sie für die eigene Installation nach.
+
+| Abweichung | Auswirkung | Behandlung im SDK |
+|---|---|---|
+| **Kommandos müssen kleingeschrieben sein.** Der Server dispatcht ohne `toLowerCase()` (`db-base/redisHandler.js`), registriert seine Handler aber nur klein. ioredis sendet zufällig klein, redis-py sendet groß. | `GET …` → `-Error GET NOT SUPPORTED`, `get …` → `4`. Ohne Behandlung scheitert der erste Befehl. | `connection.py` hängt sich vor den Command-Packer von redis-py. Synchron über `_command_packer`, asynchron über `pack_command` — redis-py benutzt je nach Modus einen anderen Weg. |
+| **Kein `HELLO`.** redis-py verhandelt RESP3 beim Verbinden. | Verbindungsaufbau scheitert mit `HELLO NOT SUPPORTED`. | `protocol=2`, dazu `lib_name=None` gegen `CLIENT SETINFO`. |
+| **Kein `PING`** auf der States-DB. | Übliche Verbindungstests schlagen fehl. | Verbindungstest über `get meta.states.protocolVersion` — die Version muss ohnehin geprüft werden. |
+| **Kein `SCAN`** auf der States-DB. Die Objects-DB kann `scan`, `sscan`, `sadd`, `eval`. | Schlüssel müssen mit `keys` gesucht werden. | `DbConfig.is_builtin` unterscheidet; gegen echtes Redis ist `keys` blockierend und muss vermieden werden. |
+| **Pub/Sub liefert den Kanal ohne `io.`-Präfix.** Echtes Redis liefert ihn mit. | Wer stur das Präfix abschneidet, verstümmelt IDs. | Das SDK toleriert beides — genau wie der JS-Client. |
+| **Abgelaufene States melden sich anders.** Kein `__keyevent@0__:expired`; stattdessen kommt `null` auf dem State-Kanal selbst. | Gegen echtes Redis wäre ein zusätzliches Abo nötig. | `null` wird als „State weg“ an `on_state_change` gemeldet. |
+
+Dazu eine Eigenschaft, die kein Fehler, aber wichtig ist: **die Rechteprüfung
+sitzt im JS-Client, nicht im Datenbankserver.** Wer direkt auf der
+Redis-Verbindung sitzt, hat faktisch Adminrechte. Das gilt für Node-Adapter
+genauso — nur kommt bei Python fremder Code aus PyPI mit in den Prozess.
+
+## Capability-Probe
+
+```bash
+python tools/probe.py
+```
+
+(aus dem [Repository](https://github.com/ioBroker/iobroker-python), nicht im Wheel enthalten)
+
+Meldet für die eigene Installation, was die beiden Datenbanken können, und macht
+anschließend einen vollständigen Round-Trip: Objekt anlegen, State schreiben,
+Änderung empfangen. Räumt mit `--cleanup` wieder auf.
+
+## Lebenszyklus
+
+`alive`, `connected`, `uptime` und `memRss` schreibt der Adapter selbst über die
+States-DB — genauso wie ein Node-Adapter. Der Stopp läuft über den
+`sigKill`-State: setzt der Controller ihn auf `-1`, beendet sich der Adapter
+geordnet. Damit funktioniert das Anhalten auch unter Windows, wo es kein
+`SIGTERM` gibt.
+
+## Entwicklung
+
+```bash
+python -m venv .venv && .venv/Scripts/activate   # Windows
+pip install -e ".[dev]"
+python examples/minimal_adapter.py --instance 0
+```
+
+## Lizenz
+
+MIT

iobroker-0.1.0/examples/minimal_adapter.py

@@ -0,0 +1,108 @@
+"""Kleinster vollstaendiger Python-Adapter.
+
+Legt zwei Objekte an, schreibt alle drei Sekunden einen Messwert und nimmt
+Schaltbefehle entgegen. Zeigt damit alle Bausteine, die ein echter Adapter
+braucht: Objekte, States, ack-Semantik, Messagebox, Logging, Shutdown.
+
+    python examples/minimal_adapter.py --instance 0
+
+Danach im Admin unter "pyexample.0" nachsehen.
+Aufraeumen: python examples/minimal_adapter.py --cleanup
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import sys
+import time
+
+sys.path.insert(0, "src")
+
+from iobroker import Adapter, Message, State  # noqa: E402
+
+
+class ExampleAdapter(Adapter):
+    async def on_ready(self) -> None:
+        await self.set_object_not_exists(
+            "temperature",
+            {
+                "type": "state",
+                "common": {
+                    "name": "Temperatur",
+                    "type": "number",
+                    "role": "value.temperature",
+                    "unit": "°C",
+                    "read": True,
+                    "write": False,
+                },
+            },
+        )
+        await self.set_object_not_exists(
+            "switch",
+            {
+                "type": "state",
+                "common": {
+                    "name": "Schalter",
+                    "type": "boolean",
+                    "role": "switch",
+                    "read": True,
+                    "write": True,
+                },
+            },
+        )
+        await self.set_object_not_exists(
+            "info.connection",
+            {
+                "type": "state",
+                "common": {
+                    "name": "Verbunden",
+                    "type": "boolean",
+                    "role": "indicator.connected",
+                    "read": True,
+                    "write": False,
+                },
+            },
+        )
+
+        # Nur die eigenen States abonnieren -- alles andere waere Laerm.
+        await self.subscribe_states("*")
+        await self.set_state("info.connection", True, ack=True)
+
+        self._worker = asyncio.create_task(self._measure())
+
+    async def _measure(self) -> None:
+        """Simuliert eine Messquelle."""
+        try:
+            while True:
+                value = round(20 + 2 * math.sin(time.time() / 10), 2)
+                # ack=True: bestaetigter Messwert, kein Befehl.
+                await self.set_state("temperature", value, ack=True)
+                await asyncio.sleep(3)
+        except asyncio.CancelledError:
+            raise
+
+    async def on_state_change(self, id: str, state: State | None) -> None:
+        if state is None:
+            self.log.debug(f"{id} geloescht oder abgelaufen")
+            return
+        # ack=False heisst: jemand will etwas schalten.
+        if not state.ack and id.endswith(".switch"):
+            self.log.info(f"Schaltbefehl: {state.val}")
+            # Geraet schalten ... und danach bestaetigen.
+            await self.set_state("switch", state.val, ack=True)
+
+    async def on_message(self, msg: Message) -> None:
+        self.log.info(f"Nachricht '{msg.command}' von {msg.from_}")
+        if msg.command == "ping":
+            await self.reply(msg, {"pong": True})
+
+    async def on_unload(self) -> None:
+        worker = getattr(self, "_worker", None)
+        if worker:
+            worker.cancel()
+        self.log.info("Aufgeraeumt")
+
+
+if __name__ == "__main__":
+    ExampleAdapter("pyexample").run()

iobroker-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "iobroker"
+version = "0.1.0"
+description = "Python-SDK fuer ioBroker-Adapter -- spricht direkt das Redis-Wire-Protokoll der States- und Objects-Datenbank"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "bluefox", email = "dogafox@gmail.com" }]
+keywords = ["iobroker", "home-automation", "adapter", "redis"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Home Automation",
+]
+dependencies = ["redis>=5.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "ruff>=0.6"]
+metrics = ["psutil>=5.9"]
+
+[project.urls]
+Homepage = "https://github.com/ioBroker/iobroker-python"
+Issues = "https://github.com/ioBroker/iobroker-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/iobroker"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

iobroker-0.1.0/src/iobroker/__init__.py

@@ -0,0 +1,30 @@
+"""iobroker -- Python-SDK fuer ioBroker-Adapter.
+
+Redet direkt das Redis-Wire-Protokoll der States- und Objects-Datenbank und
+macht Python-Prozesse damit zu gleichrangigen Adaptern neben Node.
+"""
+
+from .adapter import Adapter
+from .connection import (
+    DbConfig,
+    PROTOCOL_VERSION,
+    connect,
+    connect_async,
+    load_db_config,
+)
+from .types import Message, State, now_ms
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Adapter",
+    "State",
+    "Message",
+    "DbConfig",
+    "PROTOCOL_VERSION",
+    "connect",
+    "connect_async",
+    "load_db_config",
+    "now_ms",
+    "__version__",
+]