Skip to content
Back to top
View this page

# Python Guide

This manual covers the dsviper Python API — the Python binding of the Viper runtime. You will learn how to use the type and value system, work with databases, and leverage the full power of Viper from Python.

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

- Installation
  - Prerequisites
  - Installing from PyPI
  - Installing from the DevKit
  - Verifying Installation
  - Understanding dsviper
  - Strong-Typed Layer Over Python
  - Quick Test
  - What’s Next
- 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
  - Binary File Format
  - Common Patterns
  - Summary
  - What’s Next