Skip to content
Back to top
View this page

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