tigrbl_engine_rom 0.4.5__py3-none-any.whl

tigrbl_engine_rom/__init__.py

@@ -0,0 +1,18 @@
+"""Read-only memory engine for Tigrbl."""
+
+from .engine import ROMEngine
+from .plugin import build_rom, capabilities, register
+from .session import READ_ONLY_ERROR, ROMResult, ROMSession
+
+__all__ = [
+    "READ_ONLY_ERROR",
+    "ROMEngine",
+    "ROMResult",
+    "ROMSession",
+    "build_rom",
+    "capabilities",
+    "register",
+    "__version__",
+]
+
+__version__ = "0.4.5.dev4"

tigrbl_engine_rom/engine.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from types import MappingProxyType
+from typing import Any, Iterable, Mapping
+
+from tigrbl_base._base import EngineBase
+
+
+def _freeze(value: Any) -> Any:
+    """Return an immutable, detached representation of configuration data."""
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: _freeze(item) for key, item in value.items()})
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze(item) for item in value)
+    if isinstance(value, (set, frozenset)):
+        return frozenset(_freeze(item) for item in value)
+    return deepcopy(value)
+
+
+def _thaw(value: Any) -> Any:
+    """Return a caller-owned copy of a frozen value."""
+    if isinstance(value, Mapping):
+        return {key: _thaw(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [_thaw(item) for item in value]
+    if isinstance(value, frozenset):
+        return {_thaw(item) for item in value}
+    return deepcopy(value)
+
+
+class ROMEngine(EngineBase):
+    """Process-local immutable row image bound as an input to one table."""
+
+    def __init__(
+        self,
+        rows: Iterable[Mapping[str, Any]] | None = None,
+        *,
+        primary_key: str = "id",
+        namespace: str = "default",
+        spec: Any = None,
+    ) -> None:
+        if not isinstance(namespace, str) or not namespace:
+            raise ValueError("namespace must be a non-empty string")
+        if not isinstance(primary_key, str) or not primary_key:
+            raise ValueError("primary_key must be a non-empty string")
+        self.namespace = namespace
+        self.spec = spec
+        self.primary_key = primary_key
+        frozen_rows: list[Mapping[str, Any]] = []
+        index: dict[Any, Mapping[str, Any]] = {}
+        for position, source_row in enumerate(rows or ()):
+            if not isinstance(source_row, Mapping):
+                raise TypeError(f"row {position} must be a mapping")
+            if primary_key not in source_row:
+                raise ValueError(
+                    f"row {position} is missing primary key {primary_key!r}"
+                )
+            key = deepcopy(source_row[primary_key])
+            try:
+                duplicate = key in index
+            except TypeError as exc:
+                raise TypeError(
+                    f"primary key {primary_key!r} must be hashable"
+                ) from exc
+            if duplicate:
+                raise ValueError(f"duplicate primary key {key!r}")
+            frozen_row = _freeze(source_row)
+            frozen_rows.append(frozen_row)
+            index[key] = frozen_row
+
+        self._rows = tuple(frozen_rows)
+        self._index = MappingProxyType(index)
+
+    def to_provider(self) -> "ROMEngine":
+        """Expose this immutable engine as its own provider-like object."""
+        return self
+
+    async def _executeloop_impl(self, statements: Any) -> Any:
+        from .session import ROMSession
+
+        session = ROMSession(self)
+        try:
+            return await session.executeloop(statements)
+        finally:
+            await session.close()
+
+    async def _executemany_impl(self, stmt: Any, parameter_sets: Any) -> Any:
+        from .session import ROMSession
+
+        session = ROMSession(self)
+        try:
+            return await session.executemany(stmt, parameter_sets)
+        finally:
+            await session.close()
+
+    def get(self, ident: Any) -> dict[str, Any] | None:
+        row = self._index.get(ident)
+        return None if row is None else _thaw(row)
+
+    def scan(self) -> list[dict[str, Any]]:
+        return [_thaw(row) for row in self._rows]
+
+
+__all__ = ["ROMEngine"]

tigrbl_engine_rom/plugin.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any
+
+from tigrbl.engine.registry import register_engine
+
+from .engine import ROMEngine
+from .session import ROMSession
+
+
+def capabilities(*, spec: Any = None, mapping: Any = None) -> dict[str, Any]:
+    return {
+        "engine": "rom",
+        "transactional": False,
+        "async_native": True,
+        "isolation_levels": set(),
+        "read_only_enforced": True,
+        "persistence": "process",
+        "storage": "immutable-memory",
+        "read_consistency": "immutable-snapshot",
+        "binding_scopes": {"table"},
+    }
+
+
+def build_rom(*, mapping=None, spec=None, dsn=None, **_: Any) -> tuple[object, object]:
+    if dsn:
+        raise ValueError("ROM engine accepts embedded mapping data, not a DSN")
+    config = dict(mapping or {})
+    engine = ROMEngine(
+        rows=config.get("rows"),
+        primary_key=str(config.get("primary_key", "id")),
+        namespace=str(config.get("namespace", "default")),
+        spec=spec,
+    )
+
+    def sessionmaker(session_spec=None) -> ROMSession:
+        return ROMSession(engine, spec=session_spec)
+
+    return engine, sessionmaker
+
+
+class _Registration:
+    def build(self, *, mapping, spec, dsn):
+        return build_rom(mapping=mapping, spec=spec, dsn=dsn)
+
+    def capabilities(self, *, spec, mapping=None):
+        return capabilities(spec=spec, mapping=mapping)
+
+
+def register() -> None:
+    register_engine("rom", _Registration())
+
+
+__all__ = ["build_rom", "capabilities", "register"]

tigrbl_engine_rom/session.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import replace
+from typing import Any, Callable, Iterable, Mapping, Sequence
+
+from tigrbl_base._base import EngineSessionBase
+from tigrbl_core._spec.engine_session_spec import EngineSessionSpec
+
+from .engine import ROMEngine
+
+
+READ_ONLY_ERROR = "write attempted against read-only memory engine"
+
+
+class ROMResult:
+    """Small result facade compatible with Tigrbl's scalar query helpers."""
+
+    def __init__(self, items: Sequence[Any]) -> None:
+        self._items = tuple(items)
+        self.rowcount = len(self._items)
+
+    def scalars(self) -> "ROMResult":
+        return self
+
+    def all(self) -> list[Any]:
+        return list(self._items)
+
+    def first(self) -> Any | None:
+        return self._items[0] if self._items else None
+
+    def scalar_one(self) -> Any:
+        if len(self._items) != 1:
+            raise RuntimeError(f"expected exactly one row, found {len(self._items)}")
+        return self._items[0]
+
+
+class ROMSession(EngineSessionBase):
+    """Async Tigrbl session over an immutable :class:`ROMEngine` snapshot."""
+
+    def __init__(
+        self, engine: ROMEngine, spec: EngineSessionSpec | None = None
+    ) -> None:
+        enforced = replace(spec or EngineSessionSpec(), read_only=True)
+        super().__init__(enforced)
+        self._engine = engine
+        self._closed = False
+        self._tracked: dict[int, tuple[Any, dict[str, Any]]] = {}
+
+    def apply_spec(self, spec: EngineSessionSpec | None) -> None:
+        enforced = replace(spec or EngineSessionSpec(), read_only=True)
+        super().apply_spec(enforced)
+
+    def get_row(self, ident: Any) -> dict[str, Any] | None:
+        self._require_open_session()
+        return self._engine.get(ident)
+
+    def query_rows(
+        self,
+        predicate: Callable[[Mapping[str, Any]], bool] | None = None,
+    ) -> list[dict[str, Any]]:
+        self._require_open_session()
+        rows = self._engine.scan()
+        if predicate is not None:
+            rows = [row for row in rows if predicate(row)]
+        return rows
+
+    async def _tx_begin_impl(self) -> None:
+        self._require_open_session()
+
+    async def _tx_commit_impl(self) -> None:
+        self._require_open_session()
+
+    async def _tx_rollback_impl(self) -> None:
+        self._require_open_session()
+        for obj, snapshot in self._tracked.values():
+            for name, value in snapshot.items():
+                setattr(obj, name, deepcopy(value))
+
+    def _add_impl(self, obj: Any) -> None:
+        raise RuntimeError(READ_ONLY_ERROR)
+
+    async def _delete_impl(self, obj: Any) -> None:
+        raise RuntimeError(READ_ONLY_ERROR)
+
+    async def _flush_impl(self) -> None:
+        self._require_open_session()
+        for obj, snapshot in self._tracked.values():
+            if self._snapshot(obj) != snapshot:
+                raise RuntimeError(READ_ONLY_ERROR)
+
+    async def _refresh_impl(self, obj: Any) -> None:
+        self._require_open_session()
+        row = self._engine.get(getattr(obj, self._engine.primary_key))
+        if row is None:
+            return
+        for name, value in row.items():
+            setattr(obj, name, value)
+        self._track(obj)
+
+    async def _get_impl(self, model: type, ident: Any) -> Any | None:
+        self._require_open_session()
+        row = self._engine.get(ident)
+        return None if row is None else self._inflate(model, row)
+
+    async def _execute_impl(self, stmt: Any) -> ROMResult:
+        self._require_open_session()
+        if type(stmt).__name__.lower() != "select":
+            raise RuntimeError(READ_ONLY_ERROR)
+        model = self._extract_model(stmt)
+        items = [self._inflate(model, row) for row in self._engine.scan()]
+        for name, operator, value in self._extract_predicates(stmt):
+            if operator == "eq":
+                items = [item for item in items if getattr(item, name, None) == value]
+            elif operator == "in":
+                accepted = set(value)
+                items = [
+                    item for item in items if getattr(item, name, None) in accepted
+                ]
+            else:  # pragma: no cover - protected by extraction
+                raise NotImplementedError(f"unsupported ROM predicate: {operator}")
+        for name, descending in reversed(self._extract_ordering(stmt)):
+            items.sort(key=lambda item: getattr(item, name, None), reverse=descending)
+        offset = self._clause_int(getattr(stmt, "_offset_clause", None)) or 0
+        limit = self._clause_int(getattr(stmt, "_limit_clause", None))
+        items = items[max(0, offset) :]
+        if limit is not None:
+            items = items[: max(0, limit)]
+        return ROMResult(items)
+
+    async def _executeloop_impl(self, statements: Iterable[Any]) -> list[ROMResult]:
+        return [await self._execute_impl(statement) for statement in statements]
+
+    async def _executemany_impl(self, stmt: Any, parameter_sets: Any) -> Any:
+        raise RuntimeError(
+            "parameterized batch execution is unavailable on read-only memory engine"
+        )
+
+    async def _close_impl(self) -> None:
+        self._closed = True
+        self._open = False
+        self._dirty = False
+        self._tracked.clear()
+
+    def _require_open_session(self) -> None:
+        if self._closed:
+            raise RuntimeError("ROM session is closed")
+
+    def _inflate(self, model: type, row: Mapping[str, Any]) -> Any:
+        try:
+            obj = model(**row)
+        except TypeError:
+            obj = model()
+            for name, value in row.items():
+                setattr(obj, name, value)
+        self._track(obj)
+        return obj
+
+    def _track(self, obj: Any) -> None:
+        self._tracked[id(obj)] = (obj, self._snapshot(obj))
+
+    @staticmethod
+    def _snapshot(obj: Any) -> dict[str, Any]:
+        return {
+            name: deepcopy(value)
+            for name, value in vars(obj).items()
+            if not name.startswith("_sa_")
+        }
+
+    @staticmethod
+    def _extract_model(stmt: Any) -> type:
+        for description in getattr(stmt, "column_descriptions", ()):
+            entity = description.get("entity")
+            if isinstance(entity, type):
+                return entity
+        raise NotImplementedError("ROM selects must target one mapped model")
+
+    @classmethod
+    def _extract_predicates(cls, stmt: Any) -> list[tuple[str, str, Any]]:
+        predicates: list[tuple[str, str, Any]] = []
+        for criterion in getattr(stmt, "_where_criteria", ()):
+            clauses = getattr(criterion, "clauses", None)
+            if clauses is not None:
+                boolean_operator = getattr(
+                    getattr(criterion, "operator", None), "__name__", ""
+                )
+                if boolean_operator != "and_":
+                    raise NotImplementedError(
+                        "ROM supports conjunctions of equality and IN predicates only"
+                    )
+                for clause in clauses:
+                    predicates.extend(cls._extract_binary_predicate(clause))
+            else:
+                predicates.extend(cls._extract_binary_predicate(criterion))
+        return predicates
+
+    @staticmethod
+    def _extract_binary_predicate(expr: Any) -> list[tuple[str, str, Any]]:
+        name = getattr(getattr(expr, "left", None), "key", None)
+        operator_name = getattr(getattr(expr, "operator", None), "__name__", "")
+        right = getattr(expr, "right", None)
+        value = getattr(right, "effective_value", getattr(right, "value", None))
+        if not name or operator_name not in {"eq", "in_op"}:
+            raise NotImplementedError("ROM supports equality and IN predicates only")
+        return [(name, "in" if operator_name == "in_op" else "eq", value)]
+
+    @staticmethod
+    def _extract_ordering(stmt: Any) -> list[tuple[str, bool]]:
+        ordering: list[tuple[str, bool]] = []
+        for clause in getattr(stmt, "_order_by_clauses", ()):
+            element = getattr(clause, "element", clause)
+            name = getattr(element, "key", None)
+            if not name:
+                raise NotImplementedError("ROM ordering must target mapped columns")
+            modifier = getattr(getattr(clause, "modifier", None), "__name__", "")
+            ordering.append((name, modifier == "desc_op"))
+        return ordering
+
+    @staticmethod
+    def _clause_int(clause: Any) -> int | None:
+        if clause is None:
+            return None
+        value = getattr(clause, "effective_value", getattr(clause, "value", clause))
+        return int(value)
+
+
+__all__ = ["READ_ONLY_ERROR", "ROMResult", "ROMSession"]

tigrbl_engine_rom-0.4.5.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: tigrbl_engine_rom
+Version: 0.4.5
+Summary: Immutable read-only memory engine plugin for Tigrbl.
+Project-URL: Homepage, https://github.com/tigrbl/tigrbl
+Project-URL: Repository, https://github.com/tigrbl/tigrbl/tree/master/pkgs/90_engines/tigrbl_engine_rom
+Project-URL: Issues, https://github.com/tigrbl/tigrbl/issues
+Author-email: Jacob Stewart <jacob@swarmauri.com>
+License: Apache License
+        Version 2.0, January 2004
+        https://www.apache.org/licenses/LICENSE-2.0
+        
+        Copyright 2026 Swarmauri
+        
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+            https://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: engine,immutable,memory,plugin,readonly,tigrbl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.10
+Requires-Dist: tigrbl>=0.3.0.dev4
+Description-Content-Type: text/markdown
+
+<div align="center">
+<h1>tigrbl_engine_rom</h1>
+<p><strong>Immutable read-only memory engine plugin for Tigrbl.</strong></p>
+<a href="https://pypi.org/project/tigrbl_engine_rom/"><img src="https://img.shields.io/pypi/v/tigrbl_engine_rom?label=PyPI" alt="PyPI version"/></a>
+<a href="https://discord.gg/K4YTAPapjR"><img src="https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white" alt="Discord"/></a>
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-525252" alt="Apache 2.0 license"/></a>
+<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776ab" alt="Python 3.10 | 3.11 | 3.12 | 3.13 | 3.14"/></a>
+</div>
+
+## What is tigrbl_engine_rom?
+
+`tigrbl_engine_rom` loads one mapping-backed row image and serves it through Tigrbl's engine-session contract. The engine configuration is bound as an input to a table.
+
+## Why use tigrbl_engine_rom?
+
+Use it for embedded catalogs, fixtures, policy data, reference tables, and other datasets that must never change at runtime.
+
+## When should I install tigrbl_engine_rom?
+
+Install it when your application needs fast reads from a fixed memory image and should fail closed on every write.
+
+## Who is tigrbl_engine_rom for?
+
+It is for application developers shipping trusted reference data or deterministic read-only test images.
+
+## Where does tigrbl_engine_rom fit?
+
+It is a standalone package under `pkgs/90_engines` and is discovered through the `tigrbl.engine` entry-point group as kind `rom`.
+
+## How does tigrbl_engine_rom work?
+
+`ROMEngine` subclasses Tigrbl's `EngineBase`. Construction validates the bound table's rows and primary key, deeply detaches the source data, and freezes it. Reads always return caller-owned copies. Sessions force `read_only=True`, even if a caller requests otherwise.
+
+## Install
+
+```bash
+uv add tigrbl_engine_rom
+```
+
+## Surface Coverage
+
+| Surface | Value |
+|---|---|
+| Engine kind | `rom` |
+| Python import | `tigrbl_engine_rom` |
+| Entry point | `tigrbl.engine` |
+| Persistence | process-local immutable memory |
+| Supported Python | `3.10 | 3.11 | 3.12 | 3.13 | 3.14` |
+
+## What It Owns
+
+The package owns the ROM image, read-only session, plugin registration, and scalar result facade.
+
+## Public API and Import Surface
+
+Public symbols are `ROMEngine`, `ROMSession`, `ROMResult`, `build_rom`, `capabilities`, and `register`.
+
+## Usage Examples
+
+```python
+from tigrbl_engine_rom import build_rom
+
+engine, sessionmaker = build_rom(mapping={
+    "rows": [
+        {"code": "US", "name": "United States"},
+        {"code": "CA", "name": "Canada"},
+    ],
+    "primary_key": "code",
+})
+
+session = sessionmaker()
+assert session.get_row("CA")["name"] == "Canada"
+```
+
+Bind the engine configuration into a table:
+
+```python
+from tigrbl.factories.table import defineTableSpec
+
+class CountrySpec(defineTableSpec(engine={
+    "kind": "rom",
+    "rows": [
+        {"code": "US", "name": "United States"},
+        {"code": "CA", "name": "Canada"},
+    ],
+    "primary_key": "code",
+})):
+    pass
+```
+
+## How To Choose This Package
+
+Choose ROM for immutable embedded data. Choose `tigrbl_engine_inmemory` when transactions and runtime writes are required.
+
+## Related Packages
+
+- `tigrbl`
+- `tigrbl_engine_inmemory`
+- `tigrbl_engine_memkv`
+
+## Documentation Links
+
+- [Workspace docs](../../../docs/README.md)
+- [Package catalog](../../../docs/developer/PACKAGE_CATALOG.md)
+- [SSOT registry](../../../.ssot/registry.json)
+
+## Support
+
+- [Discord](https://discord.gg/K4YTAPapjR)
+- [GitHub issues](https://github.com/tigrbl/tigrbl/issues)
+
+## Certification Status
+
+The package is implemented with package-local behavioral tests. Certification remains governed by the repository SSOT registry and release workflows.
+
+## License
+
+Licensed under the Apache License, Version 2.0. See `LICENSE` and `NOTICE`.
+
+## Workspace documentation
+
+This README is the package-local distribution entry point. See [workspace documentation](../../../docs/README.md), [current conformance target](../../../docs/conformance/CURRENT_TARGET.md), [package catalog](../../../docs/developer/PACKAGE_CATALOG.md), [package layout](../../../docs/developer/PACKAGE_LAYOUT.md), and [SSOT registry](../../../.ssot/registry.json).

tigrbl_engine_rom-0.4.5.dist-info/RECORD

@@ -0,0 +1,10 @@
+tigrbl_engine_rom/__init__.py,sha256=-Vo3g8X_WlICo9l0bSAhqSeBzRUDcxUqvJsO3tjjdpg,377
+tigrbl_engine_rom/engine.py,sha256=TIThltMj8idUPMrpl68iAkZBqZKvRnKvF83eMZ6HLT8,3682
+tigrbl_engine_rom/plugin.py,sha256=E9oDh0_msL4F3xNqpa5wZIs2WGTPkMO4omXT8VYmfoM,1508
+tigrbl_engine_rom/session.py,sha256=k342vQTAq0-TNpnisyTt0lW_vghQYbULKxrV2P5ZdqA,8654
+tigrbl_engine_rom-0.4.5.dist-info/METADATA,sha256=RIrazWk42f5ohr2DD0m_TfS2ReolmtWLAjyYAE-medo,6317
+tigrbl_engine_rom-0.4.5.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+tigrbl_engine_rom-0.4.5.dist-info/entry_points.txt,sha256=KHczrTslM6l70hEoKETsz4bdq4bqsMMIX5Sg3L5xJTE,64
+tigrbl_engine_rom-0.4.5.dist-info/licenses/LICENSE,sha256=Z59l_PeraPrA4KbufxEZ0ft3xquZACI-vxI-4RYLp54,637
+tigrbl_engine_rom-0.4.5.dist-info/licenses/NOTICE,sha256=_I9mpUItIZUweT3-Ypbwn3Cdjdqfpm7v_P6b9CwYX4c,222
+tigrbl_engine_rom-0.4.5.dist-info/RECORD,,

tigrbl_engine_rom-0.4.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tigrbl_engine_rom-0.4.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[tigrbl.engine_plugins]
+rom = tigrbl_engine_rom.plugin:register

tigrbl_engine_rom-0.4.5.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/LICENSE-2.0
+
+Copyright 2026 Swarmauri
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

tigrbl_engine_rom-0.4.5.dist-info/licenses/NOTICE

@@ -0,0 +1,7 @@
+Tigrbl
+Copyright 2026 Swarmauri
+
+This product includes software developed by Swarmauri.
+
+Tigrbl is licensed under the Apache License, Version 2.0.
+See the LICENSE file distributed with this work for the full license text.