cultcache-py: export CultCacheError from the package root #176

Open
libby wants to merge 4 commits from hands/cultcache-py-closeout into main
4 changed files with 70 additions and 3 deletions

View file

@ -9,6 +9,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, depth_faults=(msgpack.exceptions.StackError,))`: 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.

View file

@ -69,6 +69,7 @@ store.
## Public Surface
- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a unique-index violation; a key held by two types on load, while the same conflict on a write is a `SchemaConflictError`, a `ValueError`) and `convert`'s (`source_missing`, `destination_exists`, a refused record). Import it from `cultcache_py`, not from the private `cache` module.
- `define_document_type(...)`
- `define_database_entry_type(...)`
- `database_entry_field(...)`
@ -184,9 +185,14 @@ digit (`0` to `9`), below.
rewritten under the definitions' own codec, records of other types keep their
bytes, and the new file is fsynced before the call returns. Open it with the
default definitions, then swap it in yourself. The source is never written. A
refused record raises `CultCacheError` naming the type, record key and code, and
refused record raises `CultCacheError` (importable from `cultcache_py`) naming the type, record key and code, and
leaves no destination; a killed run leaves the source as it was and a partial
destination, so delete the destination and run again.
- A store's `push` does not validate payload bytes: a store holds no definition, so it cannot know a record's codec (a JSON or
custom-codec payload is not one MessagePack value) and carries the bytes it is given, as it carries a foreign record. The
cache write path judges them: `put_envelope(s)` decodes the payload under the definition before any store is touched, so a
payload with bytes after its first value is refused (`ValueError`, "bytes after its first MessagePack value (refused on read)")
and nothing is written. A tail pushed straight through a store is refused at the next load.
- A JSON payload that is a single digit (`0` to `9`) is also a valid one-byte
MessagePack integer and reads as 48 to 57 under the default, with no refusal. Only a
document whose whole value is such a digit meets this; objects, lists and

View file

@ -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, convert
from .cache import CultCache, CultCacheBuilder, CultCacheError, ForeignRecord, UpdateOutcome, UpdateResult, convert
from .documents import (
MAX_PAYLOAD_DEPTH,
JSON_PAYLOAD_CODEC,
@ -30,6 +30,7 @@ __all__ = [
"BackingStore",
"CultCache",
"CultCacheBuilder",
"CultCacheError",
"CultCachePayloadDepthError",
"CultCachePayloadFormatError",
"CultCacheEnvelope",

View file

@ -1,10 +1,12 @@
"""The Python CultCache first call from docs/start/README.md. The docs show the region between the
`snippet` markers verbatim, and test_docs_show_the_tested_snippet fails when they differ."""
import tempfile
import unittest
from pathlib import Path
from cultcache_py import UpdateOutcome
import cultcache_py
from cultcache_py import CultCacheEnvelope, JsonLinesBackingStore, UpdateOutcome
# snippet:begin
import tempfile
@ -93,5 +95,62 @@ class FirstCallTests(unittest.TestCase):
self.assertIn("```python\n" + snippet + "```", docs)
class RootExportTests(unittest.TestCase):
def test_cultcacheerror_from_the_root_catches_a_convert_refusal(self) -> None:
from cultcache_py import CultCacheError, convert
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")
with tempfile.TemporaryDirectory() as directory:
source = SingleFileMessagePackBackingStore(Path(directory) / "source.cc")
source.push(CultCacheEnvelope.create(key="k", type=document.type, payload=document.encode_payload({"a": 1})))
destination = Path(directory) / "destination.cc"
destination.write_bytes(b"in the way")
with self.assertRaises(CultCacheError) as caught:
convert(source, destination, [document])
self.assertIn("destination_exists", str(caught.exception))
self.assertEqual(destination.read_bytes(), b"in the way")
def test_the_cache_write_path_refuses_a_payload_tail_and_writes_nothing(self) -> None:
document = define_document_type("tests.tail")
with tempfile.TemporaryDirectory() as directory:
for store in (
SingleFileMessagePackBackingStore(Path(directory) / "tail.cc"),
JsonLinesBackingStore(Path(directory) / "tail.jsonl"),
):
cache = CultCache.builder().register_document_type(document).add_generic_store(store).build()
tailed = document.encode_payload({"a": 1}) + b"\xc0"
with self.assertRaisesRegex(ValueError, r"1 bytes after its first MessagePack value \(refused on read\)"):
cache.put_envelope(document, CultCacheEnvelope.create(key="k", type=document.type, payload=tailed))
self.assertEqual(store.pull_all(), [], type(store).__name__)
def test_a_batch_with_one_tailed_envelope_is_refused_whole_and_earlier_records_stay(self) -> None:
document = define_document_type("tests.tail_batch")
with tempfile.TemporaryDirectory() as directory:
for store in (
SingleFileMessagePackBackingStore(Path(directory) / "batch.cc"),
JsonLinesBackingStore(Path(directory) / "batch.jsonl"),
):
name = type(store).__name__
cache = CultCache.builder().register_document_type(document).add_generic_store(store).build()
cache.put(document, "early", {"a": 0})
before = store.pull_all()
good = document.encode_payload({"a": 1})
with self.assertRaisesRegex(ValueError, r"1 bytes after its first MessagePack value \(refused on read\)"):
cache.put_envelopes(
document,
[
CultCacheEnvelope.create(key="good", type=document.type, payload=good),
CultCacheEnvelope.create(key="bad", type=document.type, payload=good + b"\xc0"),
],
)
self.assertEqual(store.pull_all(), before, name)
self.assertEqual([item.key for item in before], ["early"], name)
self.assertIsNone(cache.get(document, "good"), name)
if __name__ == "__main__":
unittest.main()