Installation

This chapter covers installing and verifying the dsviper Python module.

Prerequisites

  • Python 3.14

  • pip package manager

Installing from Distribution

Download dsviper-1.2.0.zip from the website Downloads page, then:

# Unzip the distribution
unzip dsviper-1.2.0.zip
cd dsviper-1.2.0

# Create a virtual environment (required since PEP 668)
python3 -m venv ~/venv
source ~/venv/bin/activate  # macOS/Linux
# or
~/venv/Scripts/activate     # Windows

# Install the wheel for your platform
pip install wheels/dsviper-1.2.0-*.whl

The wheels/ folder contains platform-specific wheels:

Platform

Wheel filename

macOS ARM64

dsviper-1.2.0-cp314-cp314-macosx_15_0_arm64.whl

macOS x86_64

dsviper-1.2.0-cp314-cp314-macosx_15_0_x86_64.whl

Windows x64

dsviper-1.2.0-cp314-cp314-win_amd64.whl

Linux x86_64

dsviper-1.2.0-cp314-cp314-linux_x86_64.whl

Verifying Installation

Verify that dsviper is correctly installed:

>>> import dsviper
>>> dsviper.version()
(1, 2, 0)

If you see the version tuple, dsviper is ready to use.

Understanding dsviper

dsviper is the Python extension module that provides access to the Viper runtime. Key points:

  • dsviper = Viper: Learning dsviper means learning Viper. The Python API mirrors the C++ API.

  • Strong typing: Unlike typical Python, dsviper raises exceptions immediately on type mismatches. This enforces data integrity.

  • Seamless bridge: Python natives (lists, dicts, tuples) are accepted as input since Viper’s metadata drives automatic conversion.

Core Philosophy

Understanding these principles helps you work effectively with Viper:

Metadata Everywhere Principle

Viper’s type system carries metadata at runtime. This means Type, Value, Function, Serialization, Database Persistence, and RPC all leverage the same type information. Define your types once, and Viper handles serialization, validation, and cross-language interoperability automatically.

Strong-Typed Layer Over Python

Unlike Python’s permissive duck typing, dsviper enforces types immediately. When you create a Vector<Int64>, only integers can be added. Type mismatches raise ViperError exceptions at the point of error, not downstream when data is corrupted. See Error Handling for details.

Reference Semantics + Immutable Commits

Primitive values are immutable. Containers (Vector, Map, Set) are mutable via shared_ptr (like Python references). Once committed to a database, state becomes immutable in the commit DAG. This enables safe concurrent access and version control.

Quick Test

Test the type system:

>>> from dsviper import *

# Create a vector of strings
>>> v = Value.create(TypeVector(Type.STRING))
>>> v.append("hello")
>>> v.append("world")
>>> v
['hello', 'world']

# Type checking in action
>>> v.append(42)
dsviper.ViperError: expected type 'str', got 'int'

What’s Next