Values¶

Values are instances of types. Value is the base class with factory methods for creating and converting values.

When to use: Use values to hold typed data. Primitives are immutable; containers (Vector, Map, Set, XArray) are mutable.

Quick Start¶

>>> from dsviper import Value, ValueString, ValueInt64, TypeVector, Type

Primitives construct directly; containers go through Value.create:

>>> name = ValueString("Alice")
>>> count = ValueInt64(42)
>>> numbers = Value.create(TypeVector(Type.INT64), [1, 2, 3])

Coming back out to Python objects is Value.dumps for anything, and encoded() for a primitive:

>>> Value.dumps(name)
'Alice'
>>> name.encoded()
'Alice'
>>> Value.dumps(numbers)
[1, 2, 3]

Reading an element of a container already gives a native:

>>> numbers[0]
1
>>> name.type()
string

A Value is not the Python object it wraps — str() gives the DSM representation, quotes included:

>>> isinstance(name, str)
False
>>> str(name)
"'Alice'"

Choosing the Right Pattern¶

Pattern	When to Use	Example
`ValueString("...")`	Direct primitive construction	`ValueInt64(42)`
`Value.create(type, data)`	Generic factory with type	`Value.create(t_vec, [1,2,3])`
`Value.decode(blob, type, definitions)`	Deserialize from binary	`Value.decode(blob, Type.STRING, defs.const())`
`ValueXxx.cast(value)`	Type casting	`ValueInt64.cast(v)`
`Value.dumps(value)`	Back out to Python objects	`Value.dumps(name)` → `'Alice'`
`value.encoded()`	Back out a primitive	`name.encoded()` → `'Alice'`

Base Class¶

dsviper.Value

Creates values, and converts between them and Python objects.

Primitive Values¶

`dsviper.ValueVoid`	A value of type void.
`dsviper.ValueBool`	A value of type bool.
`dsviper.ValueUInt8`	A value of type uint8.
`dsviper.ValueUInt16`	A value of type uint16.
`dsviper.ValueUInt32`	A value of type uint32.
`dsviper.ValueUInt64`	A value of type uint64.
`dsviper.ValueInt8`	A value of type int8.
`dsviper.ValueInt16`	A value of type int16.
`dsviper.ValueInt32`	A value of type int32.
`dsviper.ValueInt64`	A value of type int64.
`dsviper.ValueFloat`	A value of type float.
`dsviper.ValueDouble`	A value of type double.
`dsviper.ValueString`	A value of type string.
`dsviper.ValueBlob`	A value of type blob.
`dsviper.ValueBlobId`	A value of type blob_id.
`dsviper.ValueCommitId`	A value of type commit_id.
`dsviper.ValueUUId`	A value of type uuid.

Container Values¶

`dsviper.ValueVector`	A value of type vector<element_type>.
`dsviper.ValueVectorIter`	Iterator for ValueVector elements.
`dsviper.ValueSet`	A value of type set<element_type>.
`dsviper.ValueSetIter`	Iterator for ValueSet elements.
`dsviper.ValueMap`	A value of type map<key_type, element_type>.
`dsviper.ValueMapKeysIter`	Iterator for ValueMap keys.
`dsviper.ValueMapValuesIter`	Iterator for ValueMap values.
`dsviper.ValueMapItemsIter`	Iterator for ValueMap items (key-value pairs).
`dsviper.ValueXArray`	A value of type xarray<element_type>.
`dsviper.ValueOptional`	A value of type optional<element_type>.

Algebraic Values¶

`dsviper.ValueTuple`	A value of type tuple<T0, ...>.
`dsviper.ValueTupleIter`	Iterator for ValueTuple elements.
`dsviper.ValueVec`	A value of type vec<numeric_type, size>.
`dsviper.ValueMat`	A value of type mat<numeric_type, columns, rows>, stored column-major.
`dsviper.ValueVariant`	A value of type variant<T0, ...>.
`dsviper.ValueAny`	A value of any type.

User-Defined Values¶

`dsviper.ValueStructure`	A value of type struct.
`dsviper.ValueEnumeration`	A value of type enum.
`dsviper.ValueKey`	A value of type key<element_type>.

Value Program¶

A ValueProgram is a sequence of opcodes that describe mutations to values. Each opcode represents an atomic operation (set, update, union, subtract, etc.).

`dsviper.ValueProgram`	The sequence of opcodes a commit carries.
`dsviper.ValueOpcodeKey`	What an opcode applies to: an attachment, an instance, and that instance's concept.
`dsviper.ValueOpcode`	The base of the opcode hierarchy.
`dsviper.ValueOpcodeDocumentSet`	Writes a whole document at a key - the only opcode without a path.
`dsviper.ValueOpcodeDocumentUpdate`	Writes a value at a path inside a document.
`dsviper.ValueOpcodeMapUnion`	Adds entries to the map at a path, replacing the keys already there.
`dsviper.ValueOpcodeMapSubtract`	Removes from the map at a path the entries whose key it carries.
`dsviper.ValueOpcodeMapUpdate`	Writes entries over the keys the map at a path already holds, inserting none.
`dsviper.ValueOpcodeSetUnion`	Adds elements to the set at a path.
`dsviper.ValueOpcodeSetSubtract`	Removes elements from the set at a path.
`dsviper.ValueOpcodeXArrayInsert`	Inserts a position into the xarray at a path, before another one.
`dsviper.ValueOpcodeXArrayRemove`	Removes the element at a position of the xarray at a path.
`dsviper.ValueOpcodeXArrayUpdate`	Writes a value at a position of the xarray at a path.

Executing a program leaves a trace of the opcodes it ran, in the same vocabulary:

`dsviper.ValueProcessorTrace`	The execution of one program: whether it ran, and the opcodes it applied.
`dsviper.ValueProcessorTraceOpcode`	One step of a traced execution: the opcode, and the exception it raised if it did.