diff --git a/packages/cultcache-py/CHANGELOG.md b/packages/cultcache-py/CHANGELOG.md index 30b60850..70ee23db 100644 --- a/packages/cultcache-py/CHANGELOG.md +++ b/packages/cultcache-py/CHANGELOG.md @@ -8,6 +8,7 @@ ### Added +- `CultCacheError` is exported from the package root (`from cultcache_py import CultCacheError`); it was reachable only from the private `cultcache_py.cache` module. - `CultCache.update` and `update_global` return `UpdateResult(outcome, document)`; `UpdateOutcome` is `UPDATED`, `DECLINED` or `LOST_RACE`. The single-file store gains `read(key)` (the record and its content version, the SHA-256 C# computes) and `commit_if(envelope, expected)`, the version is the SHA-256 of the record re-encoded as `[key, schemaId, storedAt, payload]` with minimal MessagePack encodings, which is the SHA-256 of the record's stored bytes exactly when the writer encoded it minimally (every writer in this library does; a record another writer encoded with a wider-than-needed length or integer has the version of its minimal form, not of its bytes). Both looked up by the cache and not `BackingStore` protocol members (variants:cut_spec:cut-update-with-retry-py). - `read_payload_tree(type_name, payload, decoder=None)`: the exported owner of the one-value, depth-first payload read that `decode_payload` uses, for payloads read outside a definition (`cultnet-py`'s witness bundle decode needs it, so `cultnet-py` now requires `cultcache-py>=0.4.0`). The manifest version is 0.4.0, the minor these Unreleased breaking changes imply, set in this change so the workspace install resolves the new bound; the `## Unreleased` heading becomes `## [0.4.0]` when it is tagged. diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 0a03a671..f320bd97 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -69,6 +69,7 @@ store. ## Public Surface +- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a duplicate registration, a unique-index violation, a key held by two types). Import it from `cultcache_py`, not from the private `cache` module. Any `convert` refusal raised as a `CultCacheError` is caught by it too, once `convert` lands. - `define_document_type(...)` - `define_database_entry_type(...)` - `database_entry_field(...)` diff --git a/packages/cultcache-py/src/cultcache_py/__init__.py b/packages/cultcache-py/src/cultcache_py/__init__.py index 0c26cb25..2016c817 100644 --- a/packages/cultcache-py/src/cultcache_py/__init__.py +++ b/packages/cultcache-py/src/cultcache_py/__init__.py @@ -1,7 +1,7 @@ from .backing_store import BackingStore, CultCacheEnvelope from .backing_store import CultCacheSchemaCatalogEntry, CultCacheSchemaCatalogMember from . import leaves -from .cache import CultCache, CultCacheBuilder, ForeignRecord, UpdateOutcome, UpdateResult +from .cache import CultCache, CultCacheBuilder, CultCacheError, ForeignRecord, UpdateOutcome, UpdateResult from .documents import ( MAX_PAYLOAD_DEPTH, MAX_SLOT_KEY, @@ -25,6 +25,7 @@ __all__ = [ "BackingStore", "CultCache", "CultCacheBuilder", + "CultCacheError", "CultCachePayloadDepthError", "CultCacheEnvelope", "CultCacheSchemaCatalogEntry", diff --git a/packages/cultcache-py/tests/test_first_call.py b/packages/cultcache-py/tests/test_first_call.py index 232f6c7d..9b6b65dc 100644 --- a/packages/cultcache-py/tests/test_first_call.py +++ b/packages/cultcache-py/tests/test_first_call.py @@ -93,5 +93,20 @@ class FirstCallTests(unittest.TestCase): self.assertIn("```python\n" + snippet + "```", docs) +class RootExportTests(unittest.TestCase): + def test_cultcacheerror_is_importable_from_the_root_and_catches_a_cache_refusal(self) -> None: + import cultcache_py + from cultcache_py import CultCache, CultCacheError, define_document_type + from cultcache_py.cache import CultCacheError as private + + self.assertIs(CultCacheError, private) + self.assertIn("CultCacheError", cultcache_py.__all__) + document = define_document_type("tests.root_export") + cache = CultCache.builder().register_document_type(document).build() + with self.assertRaises(CultCacheError): + cache.get_required(document, "absent") + + if __name__ == "__main__": unittest.main() +