CommitAttachmentMutating

class dsviper.CommitAttachmentMutating

Bases: AttachmentGetting

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

No key can be removed once written. To empty one, create the attachment over an optional document type and set it to nil: the key then holds a nil document, and keys() still lists it and has() answers True. 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.

Every write is checked against the model before it is recorded: the document against the attachment’s type, the key against the attachment’s key type, the path against the shape of the document, and the value against what that path holds. Any of them raises, and nothing is written. So does an attachment the database has not registered with extend_definitions.

set and diff create the document a key does not hold yet. The other writes change a document in place, so they need one there. On a key that holds no document they are checked all the same, and one that passes has no effect: nothing is written, and nothing raises.

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. CommitAttachmentMutating 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.

An xarray is written by position: what was inserted, removed or changed. One whose shared positions changed order is replaced 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 the attachment’s key type does not admit 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 an xarray.

The xarray sits at path in the document attachment holds at key.

A new_position the xarray holds, or held before a removal, keeps its place: value is written there and before_position is ignored. A before_position the xarray does not hold leaves it unchanged.

keys(attachment: Attachment) → ValueSet[ValueKey]

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.