cultcache-py: export CultCacheError from the package root #176
4 changed files with 70 additions and 3 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue