cultcache-py 0.2.0__tar.gz

cultcache_py-0.2.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: cultcache-py
+Version: 0.2.0
+Summary: Python CultCache runtime for GameCult typed state.
+Author: GameCult
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: msgpack>=1.0
+
+# cultcache-py
+
+`cultcache-py` is the Python CultCache runtime. Callers work with registered
+domain documents while the cache owns schema identity, routing, globals, name
+lookups, indexes, and backing-store envelopes.
+
+It is intentionally small. It is not an ORM, a database, or distributed consensus wearing rented authority.
+
+It is the bottom of the Python CultLib stack and depends only on `msgpack`.
+`cultnet-py` (transport and wire contracts) and `cultmesh-py` (nodes,
+discovery, sessions, local server) build on it, mirroring `cultcache-rs` /
+`cultnet-rs` / `cultmesh-rs` and the npm packages.
+
+## Current Shape
+
+- document types are registered explicitly
+- a registered cache can be used in memory without attaching a backing store
+- `SingleFileMessagePackBackingStore` writes `cultcache.store.v1` snapshots:
+  `[format, schemaCatalog, records]`
+- records store raw MessagePack payload bytes under schema-catalog identity
+- payloads decode only through the registered document definition for that type
+- unknown persisted types fail closed
+- global documents are singleton-style per type
+- type-specific backing stores beat generic backing stores
+- the JSONL store uses only the Python standard library for bootstrap consumers
+- `define_database_entry_type(...)` emits Rust/C#-style slot-indexed
+  MessagePack array payloads for cross-runtime `DatabaseEntry` contracts
+
+## Example
+
+```python
+from dataclasses import dataclass, asdict
+from cultcache_py import CultCache, define_document_type
+
+@dataclass
+class Settings:
+    theme: str
+    retries: int
+
+settings_doc = define_document_type(
+    "settings",
+    encode=lambda value: asdict(value),
+    decode=lambda payload: Settings(**payload),
+    global_document=True,
+)
+
+cache = (
+    CultCache.builder()
+    .register_document_type(settings_doc)
+    .build()
+)
+
+cache.put_global(settings_doc, Settings(theme="ash", retries=3))
+settings = cache.get_required_global(settings_doc)
+```
+
+Add `JsonLinesBackingStore` or `SingleFileMessagePackBackingStore` when the
+cache should persist state; local in-memory cache reads and writes do not need a
+store.
+
+## Public Surface
+
+- `define_document_type(...)`
+- `define_database_entry_type(...)`
+- `database_entry_field(...)`
+- `define_document_registry(...)`
+- `CultCache.builder()`
+- `register_document_type(...)`
+- `register_registry(...)`
+- `register_name_lookup(...)`
+- `register_index(...)`
+- `add_backing_store(...)`
+- `add_generic_store(...)`
+- `pull_all_backing_stores()`
+- `get(...)`
+- `get_required(...)`
+- `get_all(...)`
+- `get_key_by_name(...)`
+- `get_by_name(...)`
+- `get_key_by_index(...)`
+- `get_by_index(...)`
+- `get_global(...)`
+- `get_required_global(...)`
+- `put(...)`
+- `put_envelopes(...)`
+- `put_global(...)`
+- `update(...)`
+- `update_global(...)`
+- `delete(...)`
+- `delete_global(...)`
+- `snapshot()`
+
+## Persistence Model
+
+Backing stores persist envelopes, not caller domain objects. The cache decodes payloads through registered document definitions and rejects unknown type discriminators. This keeps Python's dynamic runtime from turning persistence into an open polymorphic sewer with a cheerful docstring.
+
+`JsonLinesBackingStore` is the dependency-free control-plane store. It rewrites an atomic JSONL snapshot and base64-encodes payload bytes. It is designed for compact state spines, settings, ledgers, and bootstrap surfaces.
+
+`SingleFileMessagePackBackingStore` follows the shared CultCache v1 store shape
+used by the TypeScript, Rust, and C# runtimes:
+
+- top-level MessagePack value: `[format, schemaCatalog, records]`
+- `format`: `cultcache.store.v1`
+- catalog entries: `[schemaId, schemaName, schemaVersion, contentHash,
+  canonicalSchemaJson, compatibleSchemaIds, members]`
+- records: `[key, schemaId, storedAt, payload]`
+
+Large corpora should use a sharded store or a real database. A single snapshot file is a scalpel, not a forklift.
+
+## DatabaseEntry Slot Contract
+
+For cross-runtime cache entries, use `define_database_entry_type(...)` instead
+of the generic JSON formatter:
+
+```python
+from dataclasses import dataclass
+from cultcache_py import define_database_entry_type
+
+@dataclass
+class Settings:
+    theme: str
+    retries: int = 0
+
+settings_doc = define_database_entry_type(
+    "settings",
+    [
+        ("theme", 0),
+        ("retries", 1, 0),
+    ],
+    cls=Settings,
+)
+```
+
+The payload is a MessagePack array. Field keys are durable slot indexes:
+
+- key `0` writes array slot 0
+- key `4` writes array slot 4
+- unused slots are written as nil
+- deleted fields should leave their slots reserved
+- newly added fields should use new keys
+- fields with defaults tolerate missing or nil slots when older payloads are read
+
+That matches the Rust `#[derive(DatabaseEntry)]` formatter shape and the C#
+`[Key(n)]` intent: schema evolution comes from stable field slots, not source
+member order.
+
+## Wire Parity
+
+See [docs/python-runtime-parity.md](../../docs/python-runtime-parity.md) for
+the evidence map across the three Python packages.
+
+The store interop peer is `cultcache_py.interop`:
+
+```powershell
+python -m cultcache_py.interop write --file cache.cc --runtime-id python
+python -m cultcache_py.interop read --file cache.cc
+```
+
+`packages/cultcache-ts/test/cult-cache.test.ts` includes Python in the shared
+CultCache v1 parity matrix with TypeScript, Rust, and C#. `cultcache_py` ships
+a `py.typed` marker so downstream type checkers can inspect the package surface.
+
+## Tests
+
+```powershell
+$env:PYTHONPATH="$PWD\packages\cultcache-py\src"
+python -m unittest discover -s packages\cultcache-py\tests
+```
+
+The suite runs with only this package on the path. If a test here needs
+`cultnet_py` or `cultmesh_py`, it belongs in that package.

cultcache_py-0.2.0/README.md

@@ -0,0 +1,171 @@
+# cultcache-py
+
+`cultcache-py` is the Python CultCache runtime. Callers work with registered
+domain documents while the cache owns schema identity, routing, globals, name
+lookups, indexes, and backing-store envelopes.
+
+It is intentionally small. It is not an ORM, a database, or distributed consensus wearing rented authority.
+
+It is the bottom of the Python CultLib stack and depends only on `msgpack`.
+`cultnet-py` (transport and wire contracts) and `cultmesh-py` (nodes,
+discovery, sessions, local server) build on it, mirroring `cultcache-rs` /
+`cultnet-rs` / `cultmesh-rs` and the npm packages.
+
+## Current Shape
+
+- document types are registered explicitly
+- a registered cache can be used in memory without attaching a backing store
+- `SingleFileMessagePackBackingStore` writes `cultcache.store.v1` snapshots:
+  `[format, schemaCatalog, records]`
+- records store raw MessagePack payload bytes under schema-catalog identity
+- payloads decode only through the registered document definition for that type
+- unknown persisted types fail closed
+- global documents are singleton-style per type
+- type-specific backing stores beat generic backing stores
+- the JSONL store uses only the Python standard library for bootstrap consumers
+- `define_database_entry_type(...)` emits Rust/C#-style slot-indexed
+  MessagePack array payloads for cross-runtime `DatabaseEntry` contracts
+
+## Example
+
+```python
+from dataclasses import dataclass, asdict
+from cultcache_py import CultCache, define_document_type
+
+@dataclass
+class Settings:
+    theme: str
+    retries: int
+
+settings_doc = define_document_type(
+    "settings",
+    encode=lambda value: asdict(value),
+    decode=lambda payload: Settings(**payload),
+    global_document=True,
+)
+
+cache = (
+    CultCache.builder()
+    .register_document_type(settings_doc)
+    .build()
+)
+
+cache.put_global(settings_doc, Settings(theme="ash", retries=3))
+settings = cache.get_required_global(settings_doc)
+```
+
+Add `JsonLinesBackingStore` or `SingleFileMessagePackBackingStore` when the
+cache should persist state; local in-memory cache reads and writes do not need a
+store.
+
+## Public Surface
+
+- `define_document_type(...)`
+- `define_database_entry_type(...)`
+- `database_entry_field(...)`
+- `define_document_registry(...)`
+- `CultCache.builder()`
+- `register_document_type(...)`
+- `register_registry(...)`
+- `register_name_lookup(...)`
+- `register_index(...)`
+- `add_backing_store(...)`
+- `add_generic_store(...)`
+- `pull_all_backing_stores()`
+- `get(...)`
+- `get_required(...)`
+- `get_all(...)`
+- `get_key_by_name(...)`
+- `get_by_name(...)`
+- `get_key_by_index(...)`
+- `get_by_index(...)`
+- `get_global(...)`
+- `get_required_global(...)`
+- `put(...)`
+- `put_envelopes(...)`
+- `put_global(...)`
+- `update(...)`
+- `update_global(...)`
+- `delete(...)`
+- `delete_global(...)`
+- `snapshot()`
+
+## Persistence Model
+
+Backing stores persist envelopes, not caller domain objects. The cache decodes payloads through registered document definitions and rejects unknown type discriminators. This keeps Python's dynamic runtime from turning persistence into an open polymorphic sewer with a cheerful docstring.
+
+`JsonLinesBackingStore` is the dependency-free control-plane store. It rewrites an atomic JSONL snapshot and base64-encodes payload bytes. It is designed for compact state spines, settings, ledgers, and bootstrap surfaces.
+
+`SingleFileMessagePackBackingStore` follows the shared CultCache v1 store shape
+used by the TypeScript, Rust, and C# runtimes:
+
+- top-level MessagePack value: `[format, schemaCatalog, records]`
+- `format`: `cultcache.store.v1`
+- catalog entries: `[schemaId, schemaName, schemaVersion, contentHash,
+  canonicalSchemaJson, compatibleSchemaIds, members]`
+- records: `[key, schemaId, storedAt, payload]`
+
+Large corpora should use a sharded store or a real database. A single snapshot file is a scalpel, not a forklift.
+
+## DatabaseEntry Slot Contract
+
+For cross-runtime cache entries, use `define_database_entry_type(...)` instead
+of the generic JSON formatter:
+
+```python
+from dataclasses import dataclass
+from cultcache_py import define_database_entry_type
+
+@dataclass
+class Settings:
+    theme: str
+    retries: int = 0
+
+settings_doc = define_database_entry_type(
+    "settings",
+    [
+        ("theme", 0),
+        ("retries", 1, 0),
+    ],
+    cls=Settings,
+)
+```
+
+The payload is a MessagePack array. Field keys are durable slot indexes:
+
+- key `0` writes array slot 0
+- key `4` writes array slot 4
+- unused slots are written as nil
+- deleted fields should leave their slots reserved
+- newly added fields should use new keys
+- fields with defaults tolerate missing or nil slots when older payloads are read
+
+That matches the Rust `#[derive(DatabaseEntry)]` formatter shape and the C#
+`[Key(n)]` intent: schema evolution comes from stable field slots, not source
+member order.
+
+## Wire Parity
+
+See [docs/python-runtime-parity.md](../../docs/python-runtime-parity.md) for
+the evidence map across the three Python packages.
+
+The store interop peer is `cultcache_py.interop`:
+
+```powershell
+python -m cultcache_py.interop write --file cache.cc --runtime-id python
+python -m cultcache_py.interop read --file cache.cc
+```
+
+`packages/cultcache-ts/test/cult-cache.test.ts` includes Python in the shared
+CultCache v1 parity matrix with TypeScript, Rust, and C#. `cultcache_py` ships
+a `py.typed` marker so downstream type checkers can inspect the package surface.
+
+## Tests
+
+```powershell
+$env:PYTHONPATH="$PWD\packages\cultcache-py\src"
+python -m unittest discover -s packages\cultcache-py\tests
+```
+
+The suite runs with only this package on the path. If a test here needs
+`cultnet_py` or `cultmesh_py`, it belongs in that package.

cultcache_py-0.2.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cultcache-py"
+version = "0.2.0"
+description = "Python CultCache runtime for GameCult typed state."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "GameCult" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = ["msgpack>=1.0"]
+[project.scripts]
+cultcache-py-interop = "cultcache_py.interop:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cultcache_py = ["py.typed"]

cultcache_py-0.2.0/setup.cfg

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

cultcache_py-0.2.0/src/cultcache_py/__init__.py

@@ -0,0 +1,29 @@
+from .backing_store import BackingStore, CultCacheEnvelope
+from .backing_store import CultCacheSchemaCatalogEntry, CultCacheSchemaCatalogMember
+from .cache import CultCache, CultCacheBuilder
+from .documents import (
+    DatabaseEntryField,
+    DocumentDefinition,
+    database_entry_field,
+    define_database_entry_type,
+    define_document_registry,
+    define_document_type,
+)
+from .stores import JsonLinesBackingStore, SingleFileMessagePackBackingStore
+
+__all__ = [
+    "BackingStore",
+    "CultCache",
+    "CultCacheBuilder",
+    "CultCacheEnvelope",
+    "CultCacheSchemaCatalogEntry",
+    "CultCacheSchemaCatalogMember",
+    "DatabaseEntryField",
+    "DocumentDefinition",
+    "JsonLinesBackingStore",
+    "SingleFileMessagePackBackingStore",
+    "database_entry_field",
+    "define_database_entry_type",
+    "define_document_registry",
+    "define_document_type",
+]

cultcache_py-0.2.0/src/cultcache_py/backing_store.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class CultCacheSchemaCatalogMember:
+    slot: int
+    member_name: str
+    type_name: str
+    is_reference: bool = False
+    is_many: bool = False
+    target_schema_name: str | None = None
+    is_name: bool = False
+    index_alias: str | None = None
+
+
+@dataclass(frozen=True)
+class CultCacheSchemaCatalogEntry:
+    schema_id: str
+    schema_name: str
+    schema_version: str
+    content_hash: str
+    canonical_schema_json: str
+    compatible_schema_ids: tuple[str, ...] = field(default_factory=tuple)
+    members: tuple[CultCacheSchemaCatalogMember, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class CultCacheEnvelope:
+    key: str
+    type: str
+    payload: bytes
+    stored_at: str
+    schema_id: str | None = None
+    catalog_entry: CultCacheSchemaCatalogEntry | None = None
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        key: str,
+        type: str,
+        payload: bytes,
+        schema_id: str | None = None,
+        catalog_entry: CultCacheSchemaCatalogEntry | None = None,
+    ) -> "CultCacheEnvelope":
+        return cls(
+            key=key,
+            type=type,
+            payload=payload,
+            stored_at=datetime.now(timezone.utc).isoformat(),
+            schema_id=schema_id,
+            catalog_entry=catalog_entry,
+        )
+
+
+class BackingStore(Protocol):
+    def pull_all(self) -> list[CultCacheEnvelope]:
+        ...
+
+    def push(self, envelope: CultCacheEnvelope) -> None:
+        ...
+
+    def delete(self, type: str, key: str) -> None:
+        ...
+
+    def push_all(self, envelopes: list[CultCacheEnvelope]) -> None:
+        existing = {
+            (envelope.type, envelope.key): envelope for envelope in self.pull_all()
+        }
+        for envelope in envelopes:
+            existing[(envelope.type, envelope.key)] = envelope
+        self._replace_all(list(existing.values()))
+
+    def _replace_all(self, envelopes: list[CultCacheEnvelope]) -> None:
+        ...