Serialization¶

Serialization classes provide binary and token-based encoding/decoding.

When to use: Use Value.encode() / Value.decode() for binary serialization. Use streams for low-level I/O and custom protocols.

Quick Start¶

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

>>> defs = Definitions().const()
>>> blob = Value.encode(ValueString("hello"))
>>> blob
blob(13)

Decoding a primitive hands back the Python object directly, not a Value:

>>> Value.decode(blob, Type.STRING, defs)
'hello'

A container comes back as a Value. The type passed to decode is the one the blob was encoded from:

>>> t_vec = TypeVector(Type.INT64)
>>> blob = Value.encode(Value.create(t_vec, [1, 2, 3]))
>>> Value.dumps(Value.decode(blob, t_vec, defs))
[1, 2, 3]

JSON Serialization¶

For web integration and REST APIs, use Value.json_encode() and Value.json_decode().

from dsviper import Value, ValueString, Type, Definitions

# Encode primitive to JSON
value = ValueString("hello")
json_str = Value.json_encode(value)  # '"hello"'

# Decode JSON (requires type and definitions)
defs = Definitions()
decoded = Value.json_decode(json_str, Type.STRING, defs.const())

Flask REST API Example¶

Real-world pattern for exposing Viper C++ data via REST:

from flask import Flask, make_response
from dsviper import CommitDatabase, CommitStateBuilder, Value

app = Flask(__name__)

@app.get("/material/<uuid:instance_id>")
def material_api(instance_id):
    db = CommitDatabase.open("model.cdb")
    doc = CommitStateBuilder.state(db, db.last_commit_id()).attachment_getting().get(
        MY_APP_A_MATERIAL_RENDER, ValueKey.create(MY_APP_T_MATERIAL, str(instance_id))
    )
    db.close()

    # Encode document to JSON with indentation
    json_string = Value.json_encode(doc, indent=2)
    res = make_response(json_string)
    res.mimetype = "application/json"
    return res

DSM schema can also be exported for client-side validation:

@app.get("/schema")
def schema_api():
    db = CommitDatabase.open("model.cdb")
    dsm_defs = db.definitions().to_dsm_definitions()
    db.close()

    json_string = dsm_defs.json_encode(indent=2)
    res = make_response(json_string)
    res.mimetype = "application/json"
    return res

XML Serialization¶

The XML dialect of the type-driven serializer, alongside JSON — use Value.to_xml_string() / Value.from_xml_string() when a downstream consumer expects XML. As with JSON, decoding requires the type and definitions.

from dsviper import Value, ValueString, Type, Definitions

# Encode primitive to XML
value = ValueString("hello")
xml_str = Value.to_xml_string(value, indent=2)

# Decode XML (requires type and definitions)
defs = Definitions()
decoded = Value.from_xml_string(xml_str, Type.STRING, defs.const())

A parsed DSM schema serializes to XML the same way, via DSMDefinitions.to_xml_string(indent=...) / DSMDefinitions.from_xml_string(string).

Choosing the Right Approach¶

Use Case	API	Note
Binary serialization	`Value.encode()`	Default codec
Binary deserialization	`Value.decode()`	Requires type + definitions
JSON for web APIs	`Value.json_encode()`	REST/web integration
XML for XML consumers	`Value.to_xml_string()`	Same type-driven codec, XML dialect
Custom codec	`Codec.STREAM_*`	Raw, binary, token formats
File I/O	`StreamWriterFile`	Low-level streaming

Codec¶

`dsviper.Codec`	The registry of named codecs: ask for one by name with query() or check(), or take STREAM_RAW, STREAM_BINARY or STREAM_TOKEN_BINARY directly.
`dsviper.StreamCodecInstancing`	Creates the encoder, the decoder and the sizer of one codec.
`dsviper.Fuzzer`	Generates random values against a set of definitions.

Binary Streams¶

`dsviper.StreamBinaryReader`	Reads values in a fixed byte order, portable across machines.
`dsviper.StreamBinaryWriter`	Writes values in a fixed byte order, portable across machines.
`dsviper.StreamTokenBinaryReader`	Reads a portable binary stream that carries a type token per value.
`dsviper.StreamTokenBinaryWriter`	Writes a portable binary stream with a type token per value.

Stream I/O¶

`dsviper.StreamReaderBlob`	Reads data from a blob.
`dsviper.StreamReaderFile`	Reads data from a file.
`dsviper.StreamReaderSharedMemory`	Reads data from a shared memory region.
`dsviper.StreamWriterBlob`	Writes data to a blob.
`dsviper.StreamWriterFile`	Writes data to a file.
`dsviper.StreamWriterSharedMemory`	Writes data to a shared memory region.

Protocols¶

`dsviper.StreamReading`	The typed read interface.
`dsviper.StreamWriting`	The typed write interface.
`dsviper.StreamEncoding`	Writes typed values into a blob.
`dsviper.StreamDecoding`	Reads typed values back from a blob.
`dsviper.StreamSizing`	Computes how many bytes the fixed-width types occupy under one codec.

Raw Streams¶

`dsviper.StreamRawReader`	Reads values in the machine's own byte order.
`dsviper.StreamRawWriter`	Writes values in the machine's own byte order.
`dsviper.StreamRawReading`	An opaque handle on a byte source, whose one operation is size().
`dsviper.StreamRawWriting`	An opaque handle on a byte sink, with no operation of its own.