AttachmentMutating

class dsviper.AttachmentMutating

Bases: AttachmentGetting

Expresses fine-grained mutations of the documents attached to keys.

No key can be removed once written. To make one hold nothing, declare the attachment over an optional document type and set it to nil: the key remains, holding nothing. A Database, which keeps only the current state, has delete instead.

What a key holds can be replaced whole with set, or rewritten inside the document with update, the subtract_* methods and remove_in_xarray - but the key itself stays.

Every write is checked against the model before it is recorded: the document against the attachment’s type, the key against the concept the attachment files, the path against the shape of the document, and the value against what that path holds. Any of them raises, and nothing is written. A key that does not exist yet is created rather than refused.

Note: Not directly instantiable.

attachment(attachment_runtime_id: ValueUUId) → Attachment

Return the attachment attachment_runtime_id names, or raise if the definitions hold none.

attachment_getting() → AttachmentGetting

Return this object seen through the AttachmentGetting interface.

The two are views of one object: what comes back reads the same documents, not a copy, so a later write through this one is visible there. AttachmentMutating does derive from AttachmentGetting - in C++ and in both bindings - so passing it where a reader is expected already works; this exists to say which view you mean.

definitions() → DefinitionsConst

Return the Definitions every value reachable here is typed by.

diff(attachment: Attachment, key: ValueKey, value: _InputValues, *, recursive: bool = False) → None

Write only what differs between value and what attachment holds at key.

recursive computes the difference field by field inside a structure, instead of replacing it whole.

This writes; AttachmentGetting.diff_keys only reports.

enumerate(attachment: Attachment, *, encoded: Literal[True] = True) → list[tuple[ValueKey, _OutputValues]]

Return every (key, document) pair attachment holds.

encoded=False returns each document as a Value rather than a native object.

get(attachment: Attachment, key: ValueKey) → ValueOptional

Return a ValueOptional over the document attachment holds at key.

Always a ValueOptional, never None: ask is_nil() whether it holds anything, and unwrap() for the document itself.

An absent document answers a nil ValueOptional; a key of another concept than the one attachment files raises, so is_nil() reports absence and never a mismatched key.

The document comes back as a copy; mutating it does not reach what is stored.

has(attachment: Attachment, key: ValueKey) → bool

Return True if attachment holds a document at key.

insert_in_xarray(attachment: Attachment, key: ValueKey, path: PathConst, before_position: ValueUUId, new_position: ValueUUId, value: _InputValues) → None

Insert value at new_position, before before_position, in the xarray at path inside the document attachment holds at key.

keys(attachment: Attachment) → ValueSet

Return every key attachment holds a document for.

The set is taken now: a later write does not reach it.

remove_in_xarray(attachment: Attachment, key: ValueKey, path: PathConst, position: ValueUUId) → None

Remove position from the xarray at path, in the document attachment holds at key.

set(attachment: Attachment, key: ValueKey, value: _InputValues) → None

Write value into attachment at key, replacing what was there.

The value is copied in: mutating it afterwards does not reach what was written, and writing the same object under two keys stores two independent documents.

subtract_in_map(attachment: Attachment, key: ValueKey, path: PathConst, value: _InputValues) → None

Remove from the map at path, in the document attachment holds at key, the entries whose map key is in value.

subtract_in_set(attachment: Attachment, key: ValueKey, path: PathConst, value: _InputValues) → None

Remove the elements of value from the set at path, in the document attachment holds at key.

union_in_map(attachment: Attachment, key: ValueKey, path: PathConst, value: _InputValues) → None

Add the entries of value to the map at path, in the document attachment holds at key, replacing the map keys already there.

union_in_set(attachment: Attachment, key: ValueKey, path: PathConst, value: _InputValues) → None

Add the elements of value to the set at path, in the document attachment holds at key.

update(attachment: Attachment, key: ValueKey, path: PathConst, value: _InputValues) → None

Write value at path, inside the document attachment holds at key.

update_in_map(attachment: Attachment, key: ValueKey, path: PathConst, value: _InputValues) → None

Update the entries of the map at path from those of value.

The map sits in the document attachment holds at key.

Only map keys already there are written; a map key that only value carries is ignored - union_in_map inserts it instead.

update_in_xarray(attachment: Attachment, key: ValueKey, path: PathConst, position: ValueUUId, value: _InputValues) → None

Write value at position, in the xarray at path inside the document attachment holds at key.