Value

class dsviper.Value

Bases: object

Creates values, and converts between them and Python objects.

Value.create(type [, initial_value]) builds one of any type; the concrete value classes, ValueInt64, ValueString and the rest, construct directly, except ValueKey, made with ValueKey.create(). Opcodes, programs, traces and iterators come from the runtime only. It also encodes and decodes.

Two words need care. decode names two things: reading a value back from the bytes of a blob (encode writes them), and converting a native given where a value is expected to that value’s type. The encoded argument of a read chooses, for a scalar, between a Python native (True) and the Value itself (False); a container is a Value either way.

Between two values, ==, <, sorted() and their kin never raise. A native operand is decoded to the value type first - for an any or a variant, to the type of the value it holds: == answers False when it cannot be, and an ordering - <, sorted() - raises TypeError, as Python does for 1 < ‘a’.

The order is the runtime’s, total across types. Two values of different types order by the kind of type, then by the type: an int64 5 sorts after an int32 9. Within one type, a vector, a set and a map order by size first, then element by element, so [3, 1, 2] sorts after [4], unlike a Python list; a string and a tuple order element by element, and an empty optional sorts first. Sets and maps keep their elements in this order.

None decoded to a Value is read by the type in context: in a slot that can be empty - an optional, an any - it is empty; as what a function returning void returns, it is the void value; where the type cannot hold it, an optional argument is absent. ValueAny.wrap() and Value.deduce() read None as the void value. void holds no data, so no optional, collection or map holds it; the void value inside an any is ValueVoid().

Ownership follows the reference semantics of the runtime: a container holds the object you give it, and a read hands back what it holds, so mutating either is visible through the other. Four things are copied instead. What has to stay sorted and unique - a set element and a map key. Anything crossing a store: set takes a copy and get hands one back, so a document is never shared with a Database or a CommitDatabase, and mutating it after writing does not reach what was written. An element of a pack-sized vector, which at() decodes afresh on each read (ValueVector.is_pack_sized). And a value of its own type given to a container constructor, which builds a deep copy (Value.create hands back the same one).

What a failing call raises - TypeError, ValueError, IndexError, KeyError or ViperError - says which layer refused it; ViperError lists them. An attribute a value does not have raises AttributeError, and a map changed while it is iterated raises RuntimeError, as Python’s own objects do.

Note: Not directly instantiable.

static bson_decode(blob: ValueBlob, type_structure: TypeStructure, definitions: DefinitionsConst) → ValueStructure

Return the struct the BSON in blob holds, read as type_structure against definitions.

static bson_encode(value: ValueStructure) → ValueBlob

Return the bson encoded blob of the value.

BSON is written from the JSON form, so it refuses infinity and not-a-number for the same reason json_encode does. Its integers are signed 64-bit: a uint64 above that range is refused here and carried by json_encode.

static collect_blob_ids(object: Value | Path | CommitProgram | CommitState | CommitMutableState) → ValueSet[ValueBlobId]

Return the set of blob_id of all referenced blob_id by the object, where object must be a Value, a Path, a CommitState, a CommitMutableState or a CommitProgram.

static collect_commit_ids(object: Value | Path | CommitProgram | CommitState | CommitMutableState) → ValueSet[ValueCommitId]

Return the set of commit_id of all referenced commit_id by the object, where object must be a Value, a Path, a CommitState, a CommitMutableState or a CommitProgram.

static copy() → _ValueT

Return a DEEP copy of a value: the containers it holds are copied too, as a container constructor copies them. Value.create, given a value, hands back that same value instead.

static create(type: Type, initial_value: _InputValues | None = None) → Value

Return a new value of type, holding initial_value when one is given.

It hands back the SAME container: a value passed as initial_value is not copied, so mutating either shows in the other. A container constructor, given a value of its type, builds a NEW container instead, a deep copy: nothing in it is shared. Given native data - a list, a dict - both build a new container and hold the Values found in it as they are: such a Value is shared, not copied.

The two are interchangeable for the immutable scalars, and differ for every container.

One exception, and it is a rule: what orders a container is COPIED. A ValueSet copies each element, which is its own key; a ValueMap copies each key and shares the value. A key that could mutate underneath would leave the container out of order.

static decode(blob: ValueBlob, type: Type, definitions: DefinitionsConst, *, stream_codec_instancing: StreamCodecInstancing | None = None, pack_sized: bool = False, encoded: Literal[True] = True) → _OutputValues

Return the value blob holds, read as type against definitions.

The blob must hold that value and nothing more: bytes left past it mean it holds another type or another codec wrote it, and decode raises.

It carries neither the type nor the definitions: the reader needs them and the codec the writer used. Definitions travel as a blob of their own - DefinitionsConst.encode(), read back by Definitions.decode(), whose codec is Codec.STREAM_TOKEN_BINARY by default.

stream_codec_instancing chooses the codec; Codec.STREAM_BINARY is used when it is None.

If pack_sized is True, a vector<T> whose T is sized (Type.is_sized) keeps its elements encoded and decodes one only when ValueVector.at reads it: the decoding cost of a large immutable resource is paid on use. See ValueVector.is_pack_sized for what that changes.

encoded=False returns a Value rather than a native object.

static deduce(value: _PythonValues) → Value

Return a Value typed from a Python object.

A Value is returned as it is. None gives void, bool bool, int int64, float double, str string, a bytes-like object blob, tuple a tuple, list a vector, dict a map, set a set. A container’s element type is the one its elements share, a variant of them when they differ, and when empty any - int64 for a set, string for a map key. Anything else raises ViperError.

static dumps(value: Value, *, json: bool = False) → _PythonValues

Return a DEEP projection to Python objects of the strong typed value, recursing all the way to the leaves - the inverse of loads.

Unlike the encoded getters (unwrap, at, and the rest), which are shallow - scalar leaves only, containers stay handles - dumps materializes nested containers too; and unlike encode, a serialization codec to bytes, it produces live Python objects.

Shapes: vector to list; tuple and vec to tuple; mat to a tuple of columns; set to set; map and structure to dict; enumeration to str; key to (instance_id, concept_runtime_id); blob to bytes; void, and an empty optional or any, to None; optional, any and variant to what they hold; uuid, commit_id and blob_id to str; xarray to (positions, deleted positions, {position: value}). If json is True then: - a set is converted to a list. - a map is converted to a list of (key, value). - a blob is converted to a base64 str.

static encode(value: Value, *, stream_codec_instancing: StreamCodecInstancing | None = None) → ValueBlob

Return a blob encoding value.

stream_codec_instancing chooses the codec; Codec.STREAM_BINARY is used when it is None.

static from_xml_string(string: str, type: Type, definitions: DefinitionsConst, *, encoded: Literal[True] = True) → _OutputValues

Return the value the XML in string holds, read as type against definitions.

It reads only what an encoder writes: a structure holds every field it declares, an empty optional included, and nothing else, so a field left out or a member the structure does not declare raises. So does a root that does not name type.

encoded=False returns a Value rather than a native object.

static hexdigest(value: Value, *, hashing: Hashing | None = None) → str

Hash the value with the hashing interface if specified else use SHA1.

Equal values have one digest: -0.0 and 0.0 hash alike, and so does every NaN.

static json_decode(string: str, type: Type, definitions: DefinitionsConst, *, encoded: Literal[True] = True) → _OutputValues

Return the value the JSON in string holds, read as type against definitions.

It reads only what an encoder writes: a structure holds every field it declares, an empty optional included, and nothing else, so a field left out or a member the structure does not declare raises.

encoded=False returns a Value rather than a native object.

static json_encode(value: Value, indent: int = -1) → str

Return value encoded as JSON.

indent gives the number of spaces per level; -1 keeps it on one line. JSON has no form for infinity or not-a-number, so a value holding one is refused here rather than written as something else; a binary codec or to_xml_string carries it. A uint64 is written as the bare number, which a reader holding numbers as doubles rounds past 2**53, and an enumeration as its case name after a dot: ‘.green’. A set is written as a list, a map as a list of [key, value] pairs, and a key as [instance id, concept runtime id] - the shapes json_decode reads back.

static loads(object: _PythonValues, type: Type, definitions: DefinitionsConst) → Value

Return a value by decoding the Python object, the inverse of dumps.

object takes the shapes dumps produces - a key as (instance id, concept runtime id), an xarray as its positions and its values - which create refuses; definitions resolves the concepts and types those shapes name by runtime id. create takes the natives a value is seamless with instead.

static read(type: Type, stream_reading: StreamReading, definitions: DefinitionsConst, *, pack_sized: bool = False) → Value

Read a value of type from stream_reading, typed against definitions.

pack_sized keeps sized elements packed, decoding them only on access.

static succ(value: Value) → Value

Return the successor of a value.

static to_xml_string(value: Value, indent: int = -1) → str

Return value encoded as XML.

indent gives the number of spaces per level; -1 keeps it on one line.

XML carries every value - infinity, not-a-number and the whole uint64 range included - and from_xml_string reads back one equal to it. An enumeration is its case name, a blob its base64.

static write(value: Value, stream_writing: StreamWriting) → None

Write value into stream_writing.