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, Definitions

# Create a value
value = ValueString("hello")

# Encode to binary blob
blob = Value.encode(value)

# Decode from binary (requires type and definitions)
defs = Definitions()
decoded = Value.decode(blob, Type.STRING, defs.const())

# Works with any type
from dsviper import TypeVector, ValueVector
t_vec = TypeVector(Type.INT64)
vec = Value.create(t_vec, [1, 2, 3])
blob = Value.encode(vec)
decoded = Value.decode(blob, t_vec, defs.const())

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 data via REST:

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

app = Flask(__name__)

@app.get("/material/<uuid:instance_id>")
def material_api(instance_id):
    db = CommitDatabase.open("model.cdb")
    doc = db.state(db.last_commit_id()).attachment_getting().get(
        MYAPP_A_Material, ValueKey.create(MYAPP_C_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

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
Custom codec	`Codec.STREAM_*`	Raw, binary, token formats
File I/O	`StreamWriterFile`	Low-level streaming

Codec¶

`dsviper.Codec`	A class used to instantiate a codec.
`dsviper.StreamCodecInstancing`	An interface used to create encoder, decoder and sizer.

Binary Streams¶

`dsviper.StreamBinaryReader`	A class used to read data through the StreamRawReading interface (handle endianness).
`dsviper.StreamBinaryWriter`	A class used to write data through the StreamRawWriting interface (handle endianness).
`dsviper.StreamTokenBinaryReader`	A class used to read through the StreamRawReading interface (handle endianness).
`dsviper.StreamTokenBinaryWriter`	A class used to write through the StreamRawWriting interface (handle endianness).

Stream I/O¶

`dsviper.StreamReaderBlob`	A class used to read data from a blob.
`dsviper.StreamReaderFile`	A class used to read data from a file.
`dsviper.StreamReaderSharedMemory`	A class used to read data from a shared memory region.
`dsviper.StreamWriterBlob`	A class used to write data to a blob.
`dsviper.StreamWriterFile`	A class used to write data to a file.
`dsviper.StreamWriterSharedMemory`	A class used to write data to a shared memory region.

Protocols¶

`dsviper.StreamReading`	An interface used to read data.
`dsviper.StreamWriting`	An interface used to read data.
`dsviper.StreamEncoding`	An interface used to write data to a blob.
`dsviper.StreamDecoding`	An interface used to read data from a blob.
`dsviper.StreamSizing`	An interface used to get the size of data.

Raw Streams¶

`dsviper.StreamRawReader`	An class used to read data through the StreamRawReading interface.
`dsviper.StreamRawWriter`	A class used to write data through the StreamRawWriting interface.
`dsviper.StreamRawReading`	An interface used to read data.
`dsviper.StreamRawWriting`	An interface to write data.