knx-telegram-store 0.1.0__tar.gz

knx_telegram_store-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Höfling
+
+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.

knx_telegram_store-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: knx-telegram-store
+Version: 0.1.0
+Summary: A standalone, host-agnostic Python library for KNX telegram persistence.
+Author: Martin Hoefling
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/XKNX/knx-telegram-store
+Project-URL: Bug-Tracker, https://github.com/XKNX/knx-telegram-store/issues
+Keywords: knx,home-assistant,persistence,storage,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.20; extra == "sqlite"
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == "sqlite"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == "postgres"
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Requires-Dist: mypy>=1.9; extra == "dev"
+Requires-Dist: aiosqlite>=0.20; extra == "dev"
+Dynamic: license-file
+
+# knx-telegram-store
+
+A standalone, host-agnostic Python library for KNX telegram persistence.
+
+## Features
+
+- **Canonical Data Model**: A unified model for KNX telegrams shared between Home Assistant and SpectrumKNX.
+- **Pluggable Backends**:
+  - **In-Memory**: Fast, deque-based storage with full filtering support.
+  - **SQLite**: Lightweight persistent storage with SQL-based filtering.
+  - **PostgreSQL + TimescaleDB**: Full-scale time-series storage.
+- **Unified Query Model**: Powerful declarative filtering including time-delta context windows and pagination.
+- **Zero Runtime Dependencies**: Core library (model, interface, in-memory) has no dependencies.
+- **Automated Schema Management**: SQL backends handle their own creation and upgrades.
+
+## Installation
+
+```bash
+pip install knx-telegram-store
+```
+
+For SQL support:
+
+```bash
+pip install knx-telegram-store[sqlite]
+pip install knx-telegram-store[postgres]
+```
+
+## Usage
+
+```python
+from datetime import datetime
+from knx_telegram_store import StoredTelegram, TelegramQuery
+from knx_telegram_store.backends.memory import MemoryStore
+
+async def main():
+    store = MemoryStore(max_size=1000)
+    await store.initialize()
+
+    telegram = StoredTelegram(
+        timestamp=datetime.now(),
+        source="1.1.1",
+        destination="1/1/1",
+        telegramtype="GroupValueWrite",
+        direction="Incoming",
+        value=22.5,
+        unit="°C"
+    )
+
+    await store.store(telegram)
+
+    query = TelegramQuery(destinations=["1/1/1"])
+    result = await store.query(query)
+    
+    for t in result.telegrams:
+        print(f"{t.timestamp}: {t.source} -> {t.destination} | {t.value} {t.unit}")
+
+    await store.close()
+```
+
+## License
+
+MIT

knx_telegram_store-0.1.0/README.md

@@ -0,0 +1,63 @@
+# knx-telegram-store
+
+A standalone, host-agnostic Python library for KNX telegram persistence.
+
+## Features
+
+- **Canonical Data Model**: A unified model for KNX telegrams shared between Home Assistant and SpectrumKNX.
+- **Pluggable Backends**:
+  - **In-Memory**: Fast, deque-based storage with full filtering support.
+  - **SQLite**: Lightweight persistent storage with SQL-based filtering.
+  - **PostgreSQL + TimescaleDB**: Full-scale time-series storage.
+- **Unified Query Model**: Powerful declarative filtering including time-delta context windows and pagination.
+- **Zero Runtime Dependencies**: Core library (model, interface, in-memory) has no dependencies.
+- **Automated Schema Management**: SQL backends handle their own creation and upgrades.
+
+## Installation
+
+```bash
+pip install knx-telegram-store
+```
+
+For SQL support:
+
+```bash
+pip install knx-telegram-store[sqlite]
+pip install knx-telegram-store[postgres]
+```
+
+## Usage
+
+```python
+from datetime import datetime
+from knx_telegram_store import StoredTelegram, TelegramQuery
+from knx_telegram_store.backends.memory import MemoryStore
+
+async def main():
+    store = MemoryStore(max_size=1000)
+    await store.initialize()
+
+    telegram = StoredTelegram(
+        timestamp=datetime.now(),
+        source="1.1.1",
+        destination="1/1/1",
+        telegramtype="GroupValueWrite",
+        direction="Incoming",
+        value=22.5,
+        unit="°C"
+    )
+
+    await store.store(telegram)
+
+    query = TelegramQuery(destinations=["1/1/1"])
+    result = await store.query(query)
+    
+    for t in result.telegrams:
+        print(f"{t.timestamp}: {t.source} -> {t.destination} | {t.value} {t.unit}")
+
+    await store.close()
+```
+
+## License
+
+MIT

knx_telegram_store-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "knx-telegram-store"
+version = "0.1.0"
+description = "A standalone, host-agnostic Python library for KNX telegram persistence."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    {name = "Martin Hoefling"}
+]
+keywords = ["knx", "home-assistant", "persistence", "storage", "telegram"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Home Automation",
+    "Framework :: AsyncIO",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/XKNX/knx-telegram-store"
+Bug-Tracker = "https://github.com/XKNX/knx-telegram-store/issues"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["knx_telegram_store*"]
+
+[tool.setuptools.package-data]
+knx_telegram_store = ["py.typed"]
+
+[project.optional-dependencies]
+sqlite = ["aiosqlite>=0.20", "sqlalchemy[asyncio]>=2.0"]
+postgres = ["asyncpg>=0.29", "sqlalchemy[asyncio]>=2.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=4.1",
+    "ruff>=0.3",
+    "mypy>=1.9",
+    "aiosqlite>=0.20"
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+exclude = [
+    ".git",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "dist",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "B", "I", "U", "UP"]
+ignore = [
+    "E501", # Line too long
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]

knx_telegram_store-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

knx_telegram_store-0.1.0/src/knx_telegram_store/__init__.py

@@ -0,0 +1,11 @@
+from .model import StoredTelegram
+from .query import TelegramQuery, TelegramQueryResult
+from .store import StoreCapabilities, TelegramStore
+
+__all__ = [
+    "StoredTelegram",
+    "TelegramQuery",
+    "TelegramQueryResult",
+    "StoreCapabilities",
+    "TelegramStore",
+]

knx_telegram_store-0.1.0/src/knx_telegram_store/backends/base_sql.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Sequence
+from datetime import timedelta
+from typing import Any
+
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    Column,
+    DateTime,
+    Double,
+    Integer,
+    MetaData,
+    String,
+    Table,
+    Text,
+    and_,
+    func,
+    select,
+)
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from ..model import StoredTelegram
+from ..query import TelegramQuery, TelegramQueryResult
+from ..store import StoreCapabilities, TelegramStore
+
+
+class BaseSQLStore(TelegramStore):
+    """Base class for SQLAlchemy-based telegram stores."""
+
+    def __init__(self, engine: AsyncEngine, max_telegrams: int | None = None) -> None:
+        """Initialize the SQL store."""
+        self.engine = engine
+        self._max_telegrams = max_telegrams
+        self._metadata = MetaData()
+        self.telegrams = Table(
+            "telegrams",
+            self._metadata,
+            Column("timestamp", DateTime(timezone=True), nullable=False, index=True),
+            Column("source", String(20), nullable=False),
+            Column("destination", String(20), nullable=False, index=True),
+            Column("telegramtype", String(50), nullable=False),
+            Column("direction", String(20), nullable=False, server_default=""),
+            Column("payload", JSON, nullable=True),
+            Column("dpt_main", Integer, nullable=True),
+            Column("dpt_sub", Integer, nullable=True),
+            Column("dpt_name", String(100), nullable=True),
+            Column("unit", String(20), nullable=True),
+            Column("value", JSON, nullable=True),
+            Column("value_numeric", Double, nullable=True),
+            Column("raw_data", Text, nullable=True),  # Hex encoded string
+            Column("data_secure", Boolean, nullable=True),
+            Column("source_name", String(255), server_default=""),
+            Column("destination_name", String(255), server_default=""),
+        )
+        self._capabilities = StoreCapabilities(
+            supports_time_range=True,
+            supports_time_delta=True,
+            supports_pagination=True,
+            supports_count=True,
+            max_storage=max_telegrams,
+        )
+
+    @property
+    def capabilities(self) -> StoreCapabilities:
+        """Return the capabilities of this backend."""
+        return self._capabilities
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Set up the store (create tables, upgrades)."""
+
+    async def close(self) -> None:
+        """Close the engine."""
+        await self.engine.dispose()
+
+    async def store(self, telegram: StoredTelegram) -> None:
+        """Persist a single telegram."""
+        await self.store_many([telegram])
+
+    async def store_many(self, telegrams: Sequence[StoredTelegram]) -> None:
+        """Persist multiple telegrams."""
+        if not telegrams:
+            return
+
+        values = [
+            {
+                "timestamp": t.timestamp,
+                "source": t.source,
+                "destination": t.destination,
+                "telegramtype": t.telegramtype,
+                "direction": t.direction,
+                "payload": t.payload,
+                "dpt_main": t.dpt_main,
+                "dpt_sub": t.dpt_sub,
+                "dpt_name": t.dpt_name,
+                "unit": t.unit,
+                "value": t.value,
+                "value_numeric": t.value_numeric,
+                "raw_data": t.raw_data,
+                "data_secure": t.data_secure,
+                "source_name": t.source_name,
+                "destination_name": t.destination_name,
+            }
+            for t in telegrams
+        ]
+
+        async with self.engine.begin() as conn:
+            await conn.execute(self.telegrams.insert(), values)
+            if self._max_telegrams:
+                await self._prune(conn)
+
+    async def _prune(self, conn: Any) -> None:
+        """Prune old telegrams if max_storage is exceeded."""
+        # Simple pruning: delete oldest rows beyond max_telegrams
+        # Note: This could be optimized for large databases
+        count_stmt = select(func.count()).select_from(self.telegrams)
+        count = await conn.scalar(count_stmt)
+        if count > self._max_telegrams:
+            to_delete = count - self._max_telegrams
+            # Use a subquery to find the IDs to delete (SQLite/Postgres compatible)
+            # Since we don't have a PK, we use the timestamp as a proxy or just delete N oldest
+            # In PostgreSQL/TimescaleDB we might want a different strategy, but for now:
+            subq = (
+                select(self.telegrams.c.timestamp)
+                .order_by(self.telegrams.c.timestamp.asc())
+                .limit(to_delete)
+            )
+            delete_stmt = self.telegrams.delete().where(
+                self.telegrams.c.timestamp.in_(subq)
+            )
+            await conn.execute(delete_stmt)
+
+    async def query(self, query: TelegramQuery) -> TelegramQueryResult:
+        """Retrieve telegrams matching the given query."""
+        stmt = select(self.telegrams)
+
+        # 1. Base Filters
+        filters: list[Any] = []
+        if query.sources:
+            filters.append(self.telegrams.c.source.in_(query.sources))
+        if query.destinations:
+            filters.append(self.telegrams.c.destination.in_(query.destinations))
+        if query.telegram_types:
+            filters.append(self.telegrams.c.telegramtype.in_(query.telegram_types))
+        if query.directions:
+            filters.append(self.telegrams.c.direction.in_(query.directions))
+        if query.dpt_mains:
+            filters.append(self.telegrams.c.dpt_main.in_(query.dpt_mains))
+
+        if query.start_time:
+            filters.append(self.telegrams.c.timestamp >= query.start_time)
+        if query.end_time:
+            filters.append(self.telegrams.c.timestamp <= query.end_time)
+
+        # 2. Time-Delta Context Logic
+        if (query.delta_before_ms > 0 or query.delta_after_ms > 0) and filters:
+            # Create a subquery for the matching pivots
+            pivots = select(self.telegrams.c.timestamp).where(and_(*filters)).alias("pivots")
+            
+            if self.engine.dialect.name == "sqlite":
+                # SQLite specific date math
+                before_str = f"-{query.delta_before_ms / 1000.0} seconds"
+                after_str = f"+{query.delta_after_ms / 1000.0} seconds"
+                
+                cond = and_(
+                    self.telegrams.c.timestamp >= func.datetime(pivots.c.timestamp, before_str),
+                    self.telegrams.c.timestamp <= func.datetime(pivots.c.timestamp, after_str)
+                )
+            else:
+                # Standard math (Postgres, etc.)
+                delta_before = timedelta(milliseconds=query.delta_before_ms)
+                delta_after = timedelta(milliseconds=query.delta_after_ms)
+                cond = and_(
+                    self.telegrams.c.timestamp >= pivots.c.timestamp - delta_before,
+                    self.telegrams.c.timestamp <= pivots.c.timestamp + delta_after
+                )
+
+            # Use EXISTS to find rows within range of any pivot
+            stmt = select(self.telegrams).where(
+                select(pivots).where(cond).exists()
+            )
+        else:
+            if filters:
+                stmt = stmt.where(and_(*filters))
+
+        # 3. Total Count (before pagination)
+        count_stmt = select(func.count()).select_from(stmt.alias("unpaginated"))
+        
+        # 4. Ordering
+        if query.order_descending:
+            stmt = stmt.order_by(self.telegrams.c.timestamp.desc())
+        else:
+            stmt = stmt.order_by(self.telegrams.c.timestamp.asc())
+
+        # 5. Pagination
+        stmt = stmt.offset(query.offset).limit(query.limit)
+
+        async with self.engine.connect() as conn:
+            total_count = await conn.scalar(count_stmt)
+            result = await conn.execute(stmt)
+            rows = result.fetchall()
+
+        telegrams = [
+            StoredTelegram(
+                timestamp=row.timestamp,
+                source=row.source,
+                destination=row.destination,
+                telegramtype=row.telegramtype,
+                direction=row.direction,
+                payload=row.payload,
+                dpt_main=row.dpt_main,
+                dpt_sub=row.dpt_sub,
+                dpt_name=row.dpt_name,
+                unit=row.unit,
+                value=row.value,
+                value_numeric=row.value_numeric,
+                raw_data=row.raw_data,
+                data_secure=row.data_secure,
+                source_name=row.source_name,
+                destination_name=row.destination_name,
+            )
+            for row in rows
+        ]
+
+        limit_reached = (total_count or 0) > (query.offset + query.limit)
+
+        return TelegramQueryResult(
+            telegrams=telegrams,
+            total_count=total_count or 0,
+            limit_reached=limit_reached,
+        )
+
+    async def count(self) -> int:
+        """Return the total number of stored telegrams."""
+        async with self.engine.connect() as conn:
+            return await conn.scalar(select(func.count()).select_from(self.telegrams)) or 0
+
+    async def clear(self) -> None:
+        """Remove all stored telegrams."""
+        async with self.engine.begin() as conn:
+            await conn.execute(self.telegrams.delete())

knx_telegram_store-0.1.0/src/knx_telegram_store/backends/memory.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Sequence
+from datetime import timedelta
+
+from ..model import StoredTelegram
+from ..query import TelegramQuery, TelegramQueryResult
+from ..store import StoreCapabilities, TelegramStore
+
+
+class MemoryStore(TelegramStore):
+    """In-memory implementation of TelegramStore using a deque."""
+
+    def __init__(self, max_telegrams: int = 500) -> None:
+        """Initialize the memory store."""
+        self._max_telegrams = max_telegrams
+        self._telegrams: deque[StoredTelegram] = deque(maxlen=max_telegrams)
+        self._capabilities = StoreCapabilities(
+            supports_time_range=True,
+            supports_time_delta=True,
+            supports_pagination=True,
+            supports_count=True,
+            max_storage=max_telegrams,
+        )
+
+    @property
+    def capabilities(self) -> StoreCapabilities:
+        """Return the capabilities of this backend."""
+        return self._capabilities
+
+    async def initialize(self) -> None:
+        """Set up the store. Idempotent."""
+
+    async def close(self) -> None:
+        """Tear down the store."""
+
+    async def store(self, telegram: StoredTelegram) -> None:
+        """Persist a single telegram."""
+        self._telegrams.append(telegram)
+
+    async def store_many(self, telegrams: Sequence[StoredTelegram]) -> None:
+        """Persist multiple telegrams in a single batch."""
+        self._telegrams.extend(telegrams)
+
+    async def query(self, query: TelegramQuery) -> TelegramQueryResult:
+        """Retrieve telegrams matching the given query."""
+        results = list(self._telegrams)
+
+        # 1. Multi-value filters (AND across, OR within)
+        if query.sources:
+            results = [t for t in results if t.source in query.sources]
+        if query.destinations:
+            results = [t for t in results if t.destination in query.destinations]
+        if query.telegram_types:
+            results = [t for t in results if t.telegramtype in query.telegram_types]
+        if query.directions:
+            results = [t for t in results if t.direction in query.directions]
+        if query.dpt_mains:
+            results = [t for t in results if t.dpt_main in query.dpt_mains]
+
+        # 2. Time range
+        if query.start_time:
+            results = [t for t in results if t.timestamp >= query.start_time]
+        if query.end_time:
+            results = [t for t in results if t.timestamp <= query.end_time]
+
+        # 3. Time-delta context window
+        if query.delta_before_ms > 0 or query.delta_after_ms > 0:
+            pivot_timestamps = [t.timestamp for t in results]
+            
+            delta_before = timedelta(milliseconds=query.delta_before_ms)
+            delta_after = timedelta(milliseconds=query.delta_after_ms)
+            
+            # Re-collect all telegrams within any pivot's window
+            # This implementation is O(N*M) but N is small for MemoryStore (500)
+            context_results = set()
+            for t in self._telegrams:
+                for pivot_ts in pivot_timestamps:
+                    if (pivot_ts - delta_before) <= t.timestamp <= (pivot_ts + delta_after):
+                        context_results.add(t)
+                        break
+            results = list(context_results)
+
+        # 4. Ordering
+        results.sort(key=lambda t: t.timestamp, reverse=query.order_descending)
+
+        total_count = len(results)
+
+        # 5. Pagination
+        start = query.offset
+        end = query.offset + query.limit
+        paginated_results = results[start:end]
+        
+        limit_reached = len(results) > end
+
+        return TelegramQueryResult(
+            telegrams=paginated_results,
+            total_count=total_count,
+            limit_reached=limit_reached,
+        )
+
+    async def count(self) -> int:
+        """Return the total number of stored telegrams."""
+        return len(self._telegrams)
+
+    async def clear(self) -> None:
+        """Remove all stored telegrams."""
+        self._telegrams.clear()

knx_telegram_store-0.1.0/src/knx_telegram_store/backends/postgres.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from sqlalchemy import inspect, text
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from .base_sql import BaseSQLStore
+
+
+class PostgresStore(BaseSQLStore):
+    """PostgreSQL + TimescaleDB implementation of TelegramStore."""
+
+    def __init__(
+        self, 
+        dsn: str, 
+        max_telegrams: int | None = None
+    ) -> None:
+        """Initialize the Postgres store."""
+        # Ensure we use asyncpg
+        if dsn.startswith("postgresql://"):
+            dsn = dsn.replace("postgresql://", "postgresql+asyncpg://", 1)
+        
+        engine = create_async_engine(dsn)
+        super().__init__(engine, max_telegrams)
+
+    async def initialize(self) -> None:
+        """Set up the database schema and perform upgrades."""
+        async with self.engine.begin() as conn:
+            # 1. Enable TimescaleDB extension
+            await conn.execute(text("CREATE EXTENSION IF NOT EXISTS timescaledb CASCADE"))
+            
+            # 2. Create table if not exists
+            await conn.run_sync(self._metadata.create_all)
+            
+            # 3. Perform column-level upgrades
+            await conn.run_sync(self._upgrade_schema)
+            
+            # 4. Convert to hypertable (idempotent)
+            await conn.execute(text(
+                "SELECT create_hypertable('telegrams', 'timestamp', if_not_exists => TRUE)"
+            ))
+
+    def _upgrade_schema(self, connection) -> None:
+        """Synchronous part of schema upgrade (run via run_sync)."""
+        inspector = inspect(connection)
+        try:
+            columns = inspector.get_columns("telegrams")
+        except Exception:
+            # Table might not exist yet
+            return
+        existing_columns = {col["name"] for col in columns}
+        
+        # 1. Handle renames from legacy SpectrumKNX schema
+        renames = {
+            "source_address": "source",
+            "target_address": "destination",
+            "telegram_type": "telegramtype",
+            "value_json": "payload",
+            "value": "value_numeric"  # Legacy value was FLOAT, library value is JSONB
+        }
+        for old, new in renames.items():
+            if old in existing_columns:
+                if new not in existing_columns:
+                    connection.execute(text(f'ALTER TABLE telegrams RENAME COLUMN "{old}" TO "{new}"'))
+                    existing_columns.remove(old)
+                    existing_columns.add(new)
+                elif old == "value":
+                    # Special case: 'value' (float) and 'value_numeric' (float) both exist.
+                    # We must move 'value' out of the way so it can be recreated as JSONB.
+                    is_float = any(c["name"] == "value" and "double" in str(c["type"]).lower() for c in columns)
+                    if is_float:
+                        connection.execute(text('ALTER TABLE telegrams RENAME COLUMN "value" TO "value_legacy_float"'))
+                        existing_columns.remove("value")
+                        existing_columns.add("value_legacy_float")
+
+        # Migrate raw_data from bytea to text (hex encoded)
+        if "raw_data" in existing_columns:
+            for col in columns:
+                if col["name"] == "raw_data" and "bytea" in str(col["type"]).lower():
+                    connection.execute(text("ALTER TABLE telegrams ALTER COLUMN raw_data TYPE TEXT USING encode(raw_data, 'hex')"))
+        
+        # 2. Ensure all library columns exist
+        expected_columns = {
+            "direction": "VARCHAR(20) DEFAULT 'Incoming'",
+            "value": "JSONB",
+            "value_numeric": "FLOAT",
+            "payload": "JSONB",
+            "dpt_name": "VARCHAR(100)",
+            "unit": "VARCHAR(20)",
+            "data_secure": "BOOLEAN",
+            "source_name": "VARCHAR(255) DEFAULT ''",
+            "destination_name": "VARCHAR(255) DEFAULT ''",
+        }
+        
+        for col_name, col_type in expected_columns.items():
+            if col_name not in existing_columns:
+                connection.execute(text(f"ALTER TABLE telegrams ADD COLUMN {col_name} {col_type}"))
+                existing_columns.add(col_name)
+
+        # 3. Data migrations for incorrect previous renames
+        if "value_legacy_float" in existing_columns and "value_numeric" in existing_columns:
+            connection.execute(text('UPDATE telegrams SET value_numeric = value_legacy_float WHERE value_numeric IS NULL AND value_legacy_float IS NOT NULL'))
+            
+        if "payload" in existing_columns and "value" in existing_columns:
+            connection.execute(text('UPDATE telegrams SET value = payload WHERE value IS NULL AND payload IS NOT NULL'))
+            # Clear payload where it was incorrectly used for JSON data
+            connection.execute(text('UPDATE telegrams SET payload = NULL WHERE value = payload'))

knx_telegram_store-0.1.0/src/knx_telegram_store/backends/sqlite.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlalchemy import inspect, text
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from .base_sql import BaseSQLStore
+
+
+class SqliteStore(BaseSQLStore):
+    """Async SQLite implementation of TelegramStore."""
+
+    def __init__(
+        self, 
+        db_path: str | Path, 
+        max_telegrams: int | None = None
+    ) -> None:
+        """Initialize the SQLite store."""
+        # Ensure parent directory exists (unless in-memory)
+        if str(db_path) != ":memory:":
+            path = Path(db_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            url = f"sqlite+aiosqlite:///{path}"
+        else:
+            url = "sqlite+aiosqlite:///:memory:"
+        
+        engine = create_async_engine(url)
+        super().__init__(engine, max_telegrams)
+
+    async def initialize(self) -> None:
+        """Set up the database schema and perform upgrades."""
+        async with self.engine.begin() as conn:
+            # 1. Create table if not exists
+            await conn.run_sync(self._metadata.create_all)
+            
+            # 2. Perform column-level upgrades
+            await conn.run_sync(self._upgrade_schema)
+
+    def _upgrade_schema(self, connection) -> None:
+        """Synchronous part of schema upgrade (run via run_sync)."""
+        inspector = inspect(connection)
+        existing_columns = {col["name"] for col in inspector.get_columns("telegrams")}
+        
+        # Define missing columns that should be added to existing schemas
+        # (e.g. from early SpectrumKNX or HA versions)
+        expected_columns = {
+            "direction": "VARCHAR(20) DEFAULT ''",
+            "payload": "JSON",
+            "dpt_name": "VARCHAR(100)",
+            "unit": "VARCHAR(20)",
+            "data_secure": "BOOLEAN",
+            "source_name": "VARCHAR(255) DEFAULT ''",
+            "destination_name": "VARCHAR(255) DEFAULT ''",
+        }
+        
+        for col_name, col_type in expected_columns.items():
+            if col_name not in existing_columns:
+                connection.execute(text(f"ALTER TABLE telegrams ADD COLUMN {col_name} {col_type}"))

knx_telegram_store-0.1.0/src/knx_telegram_store/model.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class StoredTelegram:
+    """A KNX telegram in its stored/serialized form."""
+
+    # ── Core identity ─────────────────────────────────────────────
+    timestamp: datetime                         # timezone-aware UTC
+
+    # ── Addressing ────────────────────────────────────────────────
+    source: str                                 # Individual address, e.g. "1.2.3"
+    destination: str                            # Group address, e.g. "1/2/3"
+
+    # ── Telegram classification ───────────────────────────────────
+    telegramtype: str                           # "GroupValueWrite" | "GroupValueRead" | "GroupValueResponse"
+    direction: str                              # "Incoming" | "Outgoing"
+
+    # ── Payload ───────────────────────────────────────────────────
+    payload: int | tuple[int, ...] | None = None  # Raw KNX payload (DPTBinary int or DPTArray tuple)
+
+    # ── DPT metadata ─────────────────────────────────────────────
+    dpt_main: int | None = None
+    dpt_sub: int | None = None
+    dpt_name: str | None = None
+    unit: str | None = None
+
+    # ── Decoded value (consumer-enriched at write time) ───────────
+    value: bool | str | int | float | dict[str, Any] | None = None
+
+    # ── Numeric value for time-series queries (SQL backends) ──────
+    value_numeric: float | None = None
+
+    # ── Raw bytes (hex-encoded string for JSON safety) ────────────
+    raw_data: str | None = None                 # e.g. "0a1b2c"
+
+    # ── Security ──────────────────────────────────────────────────
+    data_secure: bool | None = None
+
+    # ── Display names (consumer-enriched at write time) ───────────
+    source_name: str = ""
+    destination_name: str = ""

knx_telegram_store-0.1.0/src/knx_telegram_store/query.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .model import StoredTelegram
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class TelegramQuery:
+    """Declarative query for telegram retrieval.
+    
+    Filter semantics:
+    - Empty list = no restriction (pass-through)
+    - Within a category = OR logic (any match passes)
+    - Across categories = AND logic (must pass all active categories)
+    """
+
+    # ── Multi-value filters (OR within, AND across) ───────────────
+    sources: list[str] = field(default_factory=list)
+    destinations: list[str] = field(default_factory=list)
+    telegram_types: list[str] = field(default_factory=list)
+    directions: list[str] = field(default_factory=list)
+    dpt_mains: list[int] = field(default_factory=list)
+
+    # ── Time range ────────────────────────────────────────────────
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+
+    # ── Time-delta context window (milliseconds) ──────────────────
+    #    When set, rows matching the filters are found first, then
+    #    ALL rows within ±delta of any matching row's timestamp are
+    #    included — even if they don't match the filters themselves.
+    delta_before_ms: int = 0
+    delta_after_ms: int = 0
+
+    # ── Pagination ────────────────────────────────────────────────
+    limit: int = 25_000
+    offset: int = 0
+
+    # ── Ordering ──────────────────────────────────────────────────
+    order_descending: bool = True  # newest first by default
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class TelegramQueryResult:
+    """Result of a telegram query."""
+
+    telegrams: list[StoredTelegram]
+    total_count: int
+    limit_reached: bool      # True = more results exist beyond limit

knx_telegram_store-0.1.0/src/knx_telegram_store/store.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .model import StoredTelegram
+from .query import TelegramQuery, TelegramQueryResult
+
+
+@dataclass(frozen=True, slots=True)
+class StoreCapabilities:
+    """Declares what a backend can do natively."""
+    supports_time_range: bool = False
+    supports_time_delta: bool = False
+    supports_pagination: bool = False
+    supports_count: bool = False
+    max_storage: int | None = None  # None = unlimited
+
+
+class TelegramStore(ABC):
+    """Abstract interface for KNX telegram persistence."""
+
+    @property
+    @abstractmethod
+    def capabilities(self) -> StoreCapabilities:
+        """Return the capabilities of this backend."""
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Set up the store (create tables, open connections, etc.).
+        
+        Called once at startup. Must be idempotent.
+        """
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Tear down the store (close connections, flush buffers).
+        
+        Called once at shutdown.
+        """
+
+    @abstractmethod
+    async def store(self, telegram: StoredTelegram) -> None:
+        """Persist a single telegram."""
+
+    @abstractmethod
+    async def store_many(self, telegrams: Sequence[StoredTelegram]) -> None:
+        """Persist multiple telegrams in a single batch."""
+
+    @abstractmethod
+    async def query(self, query: TelegramQuery) -> TelegramQueryResult:
+        """Retrieve telegrams matching the given query.
+        
+        All backends MUST implement full filtering as defined in TelegramQuery.
+        """
+
+    @abstractmethod
+    async def count(self) -> int:
+        """Return the total number of stored telegrams."""
+
+    async def clear(self) -> None:
+        """Remove all stored telegrams.
+        
+        Optional — backends may raise NotImplementedError.
+        """
+        raise NotImplementedError

knx_telegram_store-0.1.0/src/knx_telegram_store.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: knx-telegram-store
+Version: 0.1.0
+Summary: A standalone, host-agnostic Python library for KNX telegram persistence.
+Author: Martin Hoefling
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/XKNX/knx-telegram-store
+Project-URL: Bug-Tracker, https://github.com/XKNX/knx-telegram-store/issues
+Keywords: knx,home-assistant,persistence,storage,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.20; extra == "sqlite"
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == "sqlite"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == "postgres"
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Requires-Dist: mypy>=1.9; extra == "dev"
+Requires-Dist: aiosqlite>=0.20; extra == "dev"
+Dynamic: license-file
+
+# knx-telegram-store
+
+A standalone, host-agnostic Python library for KNX telegram persistence.
+
+## Features
+
+- **Canonical Data Model**: A unified model for KNX telegrams shared between Home Assistant and SpectrumKNX.
+- **Pluggable Backends**:
+  - **In-Memory**: Fast, deque-based storage with full filtering support.
+  - **SQLite**: Lightweight persistent storage with SQL-based filtering.
+  - **PostgreSQL + TimescaleDB**: Full-scale time-series storage.
+- **Unified Query Model**: Powerful declarative filtering including time-delta context windows and pagination.
+- **Zero Runtime Dependencies**: Core library (model, interface, in-memory) has no dependencies.
+- **Automated Schema Management**: SQL backends handle their own creation and upgrades.
+
+## Installation
+
+```bash
+pip install knx-telegram-store
+```
+
+For SQL support:
+
+```bash
+pip install knx-telegram-store[sqlite]
+pip install knx-telegram-store[postgres]
+```
+
+## Usage
+
+```python
+from datetime import datetime
+from knx_telegram_store import StoredTelegram, TelegramQuery
+from knx_telegram_store.backends.memory import MemoryStore
+
+async def main():
+    store = MemoryStore(max_size=1000)
+    await store.initialize()
+
+    telegram = StoredTelegram(
+        timestamp=datetime.now(),
+        source="1.1.1",
+        destination="1/1/1",
+        telegramtype="GroupValueWrite",
+        direction="Incoming",
+        value=22.5,
+        unit="°C"
+    )
+
+    await store.store(telegram)
+
+    query = TelegramQuery(destinations=["1/1/1"])
+    result = await store.query(query)
+    
+    for t in result.telegrams:
+        print(f"{t.timestamp}: {t.source} -> {t.destination} | {t.value} {t.unit}")
+
+    await store.close()
+```
+
+## License
+
+MIT

knx_telegram_store-0.1.0/src/knx_telegram_store.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/knx_telegram_store/__init__.py
+src/knx_telegram_store/model.py
+src/knx_telegram_store/py.typed
+src/knx_telegram_store/query.py
+src/knx_telegram_store/store.py
+src/knx_telegram_store.egg-info/PKG-INFO
+src/knx_telegram_store.egg-info/SOURCES.txt
+src/knx_telegram_store.egg-info/dependency_links.txt
+src/knx_telegram_store.egg-info/requires.txt
+src/knx_telegram_store.egg-info/top_level.txt
+src/knx_telegram_store/backends/base_sql.py
+src/knx_telegram_store/backends/memory.py
+src/knx_telegram_store/backends/postgres.py
+src/knx_telegram_store/backends/sqlite.py
+tests/test_generic_store.py

knx_telegram_store-0.1.0/src/knx_telegram_store.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

knx_telegram_store-0.1.0/src/knx_telegram_store.egg-info/requires.txt

@@ -0,0 +1,16 @@
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23
+pytest-cov>=4.1
+ruff>=0.3
+mypy>=1.9
+aiosqlite>=0.20
+
+[postgres]
+asyncpg>=0.29
+sqlalchemy[asyncio]>=2.0
+
+[sqlite]
+aiosqlite>=0.20
+sqlalchemy[asyncio]>=2.0

knx_telegram_store-0.1.0/src/knx_telegram_store.egg-info/top_level.txt

@@ -0,0 +1 @@
+knx_telegram_store

knx_telegram_store-0.1.0/tests/test_generic_store.py

@@ -0,0 +1,135 @@
+from datetime import UTC, datetime, timedelta
+
+import pytest
+
+from knx_telegram_store import StoredTelegram, TelegramQuery
+
+
+@pytest.fixture
+def sample_telegrams():
+    now = datetime.now(UTC)
+    return [
+        StoredTelegram(
+            timestamp=now - timedelta(minutes=5),
+            source="1.1.1",
+            destination="1/1/1",
+            telegramtype="GroupValueWrite",
+            direction="Incoming",
+            value=20.0,
+            dpt_main=9
+        ),
+        StoredTelegram(
+            timestamp=now - timedelta(minutes=4),
+            source="1.1.2",
+            destination="1/1/1",
+            telegramtype="GroupValueWrite",
+            direction="Incoming",
+            value=21.0,
+            dpt_main=9
+        ),
+        StoredTelegram(
+            timestamp=now - timedelta(minutes=3),
+            source="1.1.1",
+            destination="1/1/2",
+            telegramtype="GroupValueRead",
+            direction="Outgoing",
+            value=None,
+            dpt_main=1
+        ),
+        StoredTelegram(
+            timestamp=now - timedelta(minutes=2),
+            source="1.1.3",
+            destination="1/1/1",
+            telegramtype="GroupValueResponse",
+            direction="Incoming",
+            value=22.5,
+            dpt_main=9
+        ),
+    ]
+
+@pytest.mark.asyncio
+async def test_store_and_count(store, sample_telegrams):
+    await store.store(sample_telegrams[0])
+    assert await store.count() == 1
+    
+    await store.store_many(sample_telegrams[1:])
+    assert await store.count() == 4
+
+@pytest.mark.asyncio
+async def test_query_all(store, sample_telegrams):
+    await store.store_many(sample_telegrams)
+    result = await store.query(TelegramQuery())
+    assert len(result.telegrams) == 4
+    assert result.total_count == 4
+    # Default order is descending
+    assert result.telegrams[0].timestamp > result.telegrams[-1].timestamp
+
+@pytest.mark.asyncio
+async def test_query_filters(store, sample_telegrams):
+    await store.store_many(sample_telegrams)
+    
+    # Filter by destination
+    result = await store.query(TelegramQuery(destinations=["1/1/1"]))
+    assert len(result.telegrams) == 3
+    
+    # Filter by source
+    result = await store.query(TelegramQuery(sources=["1.1.1"]))
+    assert len(result.telegrams) == 2
+    
+    # Filter by type
+    result = await store.query(TelegramQuery(telegram_types=["GroupValueRead"]))
+    assert len(result.telegrams) == 1
+    
+    # Combined filter
+    result = await store.query(TelegramQuery(destinations=["1/1/1"], dpt_mains=[9]))
+    assert len(result.telegrams) == 3
+
+@pytest.mark.asyncio
+async def test_query_time_range(store, sample_telegrams):
+    await store.store_many(sample_telegrams)
+    now = datetime.now(UTC)
+    
+    # Start time (now - 3.5 mins) should include t2 (now-3) and t3 (now-2)
+    result = await store.query(TelegramQuery(start_time=now - timedelta(minutes=3.5)))
+    assert len(result.telegrams) == 2
+    
+    # End time (now - 3.5 mins) should include t0 (now-5) and t1 (now-4)
+    result = await store.query(TelegramQuery(end_time=now - timedelta(minutes=3.5)))
+    assert len(result.telegrams) == 2
+
+@pytest.mark.asyncio
+async def test_query_time_delta(store, sample_telegrams):
+    await store.store_many(sample_telegrams)
+    
+    # Find the Read telegram (3 mins ago) and everything within 1.5 mins before/after
+    # This should include the telegram 4 mins ago (t1) and 2 mins ago (t3).
+    query = TelegramQuery(
+        telegram_types=["GroupValueRead"],
+        delta_before_ms=90000, # 1.5 mins
+        delta_after_ms=90000   # 1.5 mins
+    )
+    result = await store.query(query)
+    # Pivot is t2 (3 mins ago). 
+    # t1 (4 mins ago) is 1 min before (included)
+    # t3 (2 mins ago) is 1 min after (included)
+    # t0 (5 mins ago) is 2 mins before (excluded)
+    assert len(result.telegrams) == 3
+
+@pytest.mark.asyncio
+async def test_pagination(store, sample_telegrams):
+    await store.store_many(sample_telegrams)
+    
+    result = await store.query(TelegramQuery(limit=2, offset=0))
+    assert len(result.telegrams) == 2
+    assert result.limit_reached is True
+    
+    result = await store.query(TelegramQuery(limit=2, offset=2))
+    assert len(result.telegrams) == 2
+    assert result.limit_reached is False
+
+@pytest.mark.asyncio
+async def test_clear(store, sample_telegrams):
+    await store.store_many(sample_telegrams)
+    assert await store.count() == 4
+    await store.clear()
+    assert await store.count() == 0