dsviper

The dsviper Python runtime is the strongly typed Python API over the Viper C++ engine. It carries the type system, value system, commit DAG, database tier, serialization, and RPC, and exposes them as Python classes and functions. Most user code in the ecosystem imports dsviper and is built on top of it.

dsviper is the runtime layer of the ecosystem. It consumes typed Python packages produced by Kibo (the static API), or loads DSM models directly at runtime (the dynamic API). See Value Chains for the broader picture and Naming for how dsviper relates to DevKit and the Viper engine.

Place in the ecosystem

• Depends on — Viper (the C++ engine — see Naming).

• Consumed by — dsviper-components (Qt Widgets and QML variants), dsviper-tools (Qt Widgets and QML variants), Commit Applications (ge-py, ge-qml, web-cdbe).

• Source repository — the dsviper PyPI package is built from the Viper source. There is no separate dsviper repository on GitHub. See Naming for the distinction between distribution names and repository names.

• Distribution — dsviper on PyPI (pip install dsviper). Not bundled in the DevKit ZIP — the ZIP carries the toolchain (kibo, dsviper-tools, offline docs), but dsviper itself must be installed separately from PyPI.

Quickstart

Install:

pip install dsviper

Open a versioned database, write a typed value, commit:

from dsviper import CommitDatabase, CommitMutableState
import model.attachments as ma

db = CommitDatabase.open("model.cdb")

key = ma.Tuto_UserKey.create()
login = ma.Tuto_Login()
login.nickname = "alice"

state = CommitMutableState(db.initial_state())
ma.tuto_user_login_set(state.attachment_mutating(), key, login)
db.commit_mutations("Add user", state)

The model.attachments module above is a generated package — the static API produced by Kibo from a DSM model. For the dynamic API (no code generation, definitions loaded at runtime), see DSM Processing.

The Metadata Everywhere Principle

Viper carries its type information as runtime metadata, and every subsystem draws on the same source: types, values, functions, serialization, database persistence, and RPC. You describe your data once — either through the static API generated from a DSM model, or directly through the dynamic API — and the runtime handles conversion, validation, and cross-language interoperability for you. This is why Python natives (list, dict, tuple) can be passed directly to typed dsviper functions: the metadata drives the bridge, so there is nothing to register and nothing to glue by hand.

A complete wrapper

dsviper is a complete wrapper over Viper — the full C++ surface (types, values, runtime, database tier, commit engine, serialization, RPC) is reachable from Python. The Commit Engine in particular is documented in the peer Commit section.

Further examples

For a broader corpus of runnable usage examples, see the public test suite at digital-substrate/dsviper-tests.

Topics

• Installation
  • Prerequisites
  • Installing from PyPI
  • Installing from the DevKit
  • Verifying Installation
  • Quick Test
• Hello dsviper
• Tutorial
  • The User/Login Model
• Types and Values
  • The Universal Constructor
  • Choosing the Right Constructor
  • Type Constants
  • Primitive Types
  • Mathematical Types
  • Type Deduction
  • Type Information
  • Type Checking
  • The Seamless Bridge
• Collections
  • Vector
  • Set
  • Map
  • Optional
  • Tuple
  • Variant
  • XArray
  • Any
  • Nested Collections
• Structures and Enumerations
  • Creating Structures with Definitions
  • Instantiating Structures
  • Field Access
  • Default Values
  • Nested Structures
  • Paths
  • Enumerations
  • Type Information
  • Using Structures with Databases
• Error Handling
  • The ViperError Exception
  • Common Error Categories
  • Best Practices
  • Debugging Tips
• DSM Processing
  • The DSM Workflow
  • Step 1: Assemble
  • Step 2: Parse
  • Step 3: DSM Introspection
  • Using Runtime Definitions
  • Serialization
• Database
  • Creating a Database
  • Remote Access
  • Setting Up Definitions
  • CRUD Operations
  • Transactions
  • Lifecycle
  • Metadata
• Binary Data (Blobs)
  • Blob vs BlobId
  • ValueBlob
  • ValueBlobId
  • BlobLayout - Metadata Everywhere
  • BlobView (Read-Only)
  • BlobArray (Read-Write)
  • BlobPack - Structured Binary Data
  • NumPy Integration
  • Blob in Attachments
  • Storing Blobs in Database
  • When to Use Each Type
• Serialization
  • JSON Encoding
  • DSM Definitions Serialization
  • Binary Encoding
  • Stream Codec
  • Value Description
  • DSM Definitions File Format
  • Common Patterns

API reference

The complete class reference is in dsviper API, organised by domain: types, values, attachments, database, commit, blobs, serialization, DSM introspection, web rendering, and core utilities.

Status

Part of DevKit 1.2.x (LTS, feature-locked).