cultmesh-py: watch_by_index reads the cache's canonical index text; README teaches indexes=unique, roles=selection; role-watch and README pinned

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Libby 2026-11-11 06:46:56 +00:00
commit 630b970e06
3 changed files with 87 additions and 10 deletions

View file

@ -43,9 +43,10 @@ from cultmesh_py import (
note_doc = define_database_entry_type(
"mesh.note",
[("body", 0), ("name", 1), ("kind", 2)],
[("body", 0), ("name", 1), ("kind", 2), ("slug", 3)],
name="name",
indexes={"kind": "kind"},
indexes={"slug": "slug"}, # unique: no two notes hold one slug; watch_by_index and get_key_by_index look it up
roles={"kind": "kind"}, # many notes share a kind: a selection alias, never a lookup
)
node = CultMesh.start_node(
"mesh.cc",
@ -55,13 +56,13 @@ node = CultMesh.start_node(
node.database.register_document(note_doc)
unsubscribe = node.database.watch_record(note_doc, "note:1", lambda change: print(change.change_kind))
unsubscribe_named = node.database.watch_by_name(note_doc, "intro", lambda change: print(change.record_key))
unsubscribe_kind = node.database.watch_by_index(note_doc, "kind", "guide", lambda change: print(change.record_key))
node.database.put(note_doc, "note:1", {"body": "hello", "name": "intro", "kind": "guide"})
unsubscribe_slug = node.database.watch_by_index(note_doc, "slug", "intro-guide", lambda change: print(change.record_key))
node.database.put(note_doc, "note:1", {"body": "hello", "name": "intro", "kind": "guide", "slug": "intro-guide"})
live_note = node.database.get_required(note_doc, "note:1")
put_message = node.database.put_raw_message(
note_doc,
"note:2",
{"body": "wire me", "name": "wire", "kind": "interop"},
{"body": "wire me", "name": "wire", "kind": "interop", "slug": "wire-me"},
shard_id="interop",
shard_epoch=1,
)

View file

@ -10,7 +10,7 @@ from pathlib import Path
from typing import Any, Callable
from cultcache_py import CultCache, CultCacheEnvelope, SingleFileMessagePackBackingStore
from cultcache_py.cache import CultCacheError
from cultcache_py.cache import CultCacheError, index_text
from cultcache_py.documents import DocumentDefinition, extract_value
from cultnet_py import (
CultNetAppliedRecord,
@ -520,7 +520,7 @@ class CultMeshDatabase:
raise ValueError(f"Document type {document.type!r} has no index {index!r}")
def filtered(change: CultMeshDatabaseChange) -> None:
if self._change_matches_extractor(change, extractor, value):
if self._change_matches_extractor(change, extractor, value, index_text):
callback(self._change_as_document(change, requested))
return self.watch(filtered, document=document)
@ -1295,10 +1295,11 @@ class CultMeshDatabase:
change: CultMeshDatabaseChange,
extractor: str | Callable[[Any], str | int | float | bool | None],
expected: str,
render: Callable[[Any], str | None] = str,
) -> bool:
return (
self._value_matches_extractor(change.value, extractor, expected)
or self._value_matches_extractor(change.previous_value, extractor, expected)
self._value_matches_extractor(change.value, extractor, expected, render)
or self._value_matches_extractor(change.previous_value, extractor, expected, render)
)
def _value_matches_extractor(
@ -1306,11 +1307,12 @@ class CultMeshDatabase:
value: Any | None,
extractor: str | Callable[[Any], str | int | float | bool | None],
expected: str,
render: Callable[[Any], str | None] = str,
) -> bool:
if value is None:
return False
actual = extract_value(value, extractor)
return actual is not None and str(actual) == expected
return actual is not None and render(actual) == expected
def _previous_values_for_snapshot_response(self, response: dict[str, Any]) -> dict[tuple[str, str], Any]:
if response.get("schemaVersion") != "cultnet.snapshot_response_raw.v0":

View file

@ -0,0 +1,74 @@
from __future__ import annotations
import re
import unittest
from pathlib import Path
from cultcache_py import define_database_entry_type
from cultcache_py.cache import CultCacheError
from cultmesh_py import CultMesh
# variants:ruling:unique-indexes. `indexes` are unique lookups, `roles` are selection aliases. A watch by index reads the
# lookup's own canonical text (cultcache_py.cache.index_text), never a second rendering of the value.
class WatchByIndexTests(unittest.TestCase):
def test_the_watch_and_the_lookup_agree_on_the_text_of_a_value(self) -> None:
document = define_database_entry_type("mesh.priced", [("price", 0)], indexes={"price": "price"})
node = CultMesh.create_node(runtime_id="mesh-watch-text")
node.database.register_document(document)
cases = [
(2.0, "2", "2.0"),
(0.1, "0.1000000000000000055511151231257827021181583404541015625", "0.1"),
(-0.0, "0", "-0.0"),
]
for index, (value, text, str_text) in enumerate(cases):
with self.subTest(value=value):
key = f"item:{index}"
heard: list[str] = []
misheard: list[str] = []
node.database.watch_by_index(document, "price", text, lambda change: heard.append(change.record_key))
node.database.watch_by_index(document, "price", str_text, lambda change: misheard.append(change.record_key))
node.database.put(document, key, {"price": value})
self.assertEqual(node.database.get_by_index(document, "price", text), {"price": value})
self.assertEqual(heard, [key])
if str_text != text:
self.assertEqual(misheard, [])
self.assertIsNone(node.database.get_by_index(document, "price", str_text))
def test_a_blank_value_is_never_indexed_so_never_watched(self) -> None:
document = define_database_entry_type("mesh.blank", [("sku", 0)], indexes={"sku": "sku"})
node = CultMesh.create_node(runtime_id="mesh-watch-blank")
node.database.register_document(document)
heard: list[str] = []
node.database.watch_by_index(document, "sku", " ", lambda change: heard.append(change.record_key))
node.database.put(document, "item:1", {"sku": " "})
self.assertEqual(heard, [])
def test_a_role_alias_is_not_watchable_by_index(self) -> None:
document = define_database_entry_type("mesh.roles", [("kind", 0)], roles={"kind": "kind"})
node = CultMesh.create_node(runtime_id="mesh-watch-role")
node.database.register_document(document)
with self.assertRaisesRegex(ValueError, "has no index"):
node.database.watch_by_index(document, "kind", "guide", lambda _: None)
class ReadmeTests(unittest.TestCase):
def test_the_readme_note_document_admits_many_notes_of_one_kind(self) -> None:
readme = (Path(__file__).parents[1] / "README.md").read_text(encoding="utf-8")
declaration = re.search(r"^note_doc = define_database_entry_type\(\n.*?^\)\n", readme, re.S | re.M)
self.assertIsNotNone(declaration)
scope: dict = {"define_database_entry_type": define_database_entry_type}
exec(declaration.group(0), scope) # noqa: S102 - the README's own declaration
note_doc = scope["note_doc"]
node = CultMesh.create_node(runtime_id="mesh-readme")
node.database.register_document(note_doc)
node.database.put(note_doc, "note:1", {"body": "a", "name": "one", "kind": "guide", "slug": "one"})
node.database.put(note_doc, "note:2", {"body": "b", "name": "two", "kind": "guide", "slug": "two"})
self.assertEqual(node.database.get_by_index(note_doc, "slug", "two")["body"], "b")
with self.assertRaises(CultCacheError):
node.database.put(note_doc, "note:3", {"body": "c", "name": "three", "kind": "guide", "slug": "one"})
if __name__ == "__main__":
unittest.main()