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 DevKit, dsviper, Viper — what’s what for how dsviper relates to DevKit and the Viper engine.

Place in the ecosystem

• Depends on — Viper (the C++ engine — see DevKit, dsviper, Viper — what’s what).

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

• Source repository — the dsviper PyPI package is built from the Viper source. There is no separate dsviper repository on GitHub. See DevKit, dsviper, Viper — what’s what 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.

Topics

• Installation
  • Prerequisites
  • Installing from PyPI
  • Installing from the DevKit
  • Verifying Installation
  • Understanding dsviper
  • Strong-Typed Layer Over Python
  • Quick Test
  • What’s Next
• Hello dsviper
• Tutorial
  • The User/Login Model
  • Two Approaches
  • What’s Next
• 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
  • What’s Next
• Collections
  • Vector
  • Set
  • Map
  • Optional
  • Tuple
  • Variant
  • XArray
  • Any
  • Nested Collections
  • What’s Next
• Structures and Enumerations
  • Creating Structures with Definitions
  • Instantiating Structures
  • Field Access
  • Default Values
  • Nested Structures
  • Paths
  • Enumerations
  • Type Information
  • Using Structures with Databases
  • What’s Next
• Error Handling
  • The ViperError Exception
  • Common Error Categories
  • Best Practices
  • Debugging Tips
  • What’s Next
• DSM Processing
  • The DSM Workflow
  • Step 1: Assemble
  • Step 2: Parse
  • Step 3: DSM Introspection
  • Using Runtime Definitions
  • Serialization
  • What’s Next
• Database
  • Creating a Database
  • Remote Access
  • Setting Up Definitions
  • CRUD Operations
  • Transactions
  • Lifecycle
  • Metadata
  • Choosing Between Database and CommitDatabase
  • What’s Next
• Commit System
  • CommitDatabase
  • Opening a CommitDatabase
  • Reading State
  • Mutations
  • Complete Example
  • Path-Based Mutators
  • Commit History
  • Embedded Definitions
  • What’s Next
• The Dual-Layer Contract
  • The Contract
  • Why the Engine’s Output Is Untrusted Data
  • Three Error Families
  • What Commit Provides
  • What Commit Does NOT Provide
  • Implications for dsviper Code
  • Summary
  • See Also
• 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
  • What’s Next
• Serialization
  • JSON Encoding
  • DSM Definitions Serialization
  • Binary Encoding
  • Stream Codec
  • Value Description
  • DSM Definitions File Format
  • Common Patterns
  • Summary
  • What’s Next

API reference

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

Status

Part of DevKit 1.2.x. The runtime is stable; new APIs are added carefully with backward compatibility in mind.