# dsviper DevKit

## The Metadata Everywhere Principle

Viper is a runtime designed with a strong usage of metadata to implement many features
like Type, Value, Function, Collection, Serialization, Function Call, Database
Persistence, Plugins, Remote Procedure Call, Network Service, RemoteDatabase, Scripting in
Python and Web interoperability with JSON and Bson.

Viper was designed to simplify the way scripting language and C++ work together through
metadata. The dynamic aspect of a script interpreter use the dynamic aspect of metadata
defined in Viper for Type, Value and Function to implement a strong typed data access and
function call in a fast and lazy way.

**dsviper** (the Python C/API binding of Viper) is like a safe strong-typed layer over Python
required for C++ interoperability. dsviper raises an exception immediately on a type
mismatch, but is smart enough to accept native python values and collections as input
since the metadata drives everything in Viper.

A dsviper collection is a strong-typed version of a python collection with almost the same
API. Conversion between the two worlds is only required when you need a native python
object to compute an expression or assign a new value. dsviper and python use the same
reference semantics.

## Tested Platforms

- **macOS** (Sequoia 15, x86_64 / arm64)
- **Windows** (10, 11, x86_64 / arm64)
- **Linux Ubuntu** (24.04 LTS, x86_64 / arm64)

Python 3.14+ on all platforms. On Windows, if a DLL is missing, install the
[Microsoft Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170)
([x64](https://aka.ms/vs/17/release/vc_redist.x64.exe),
[arm64](https://aka.ms/vs/17/release/vc_redist.arm64.exe)).

## Content of the Distribution

```
    ./requirements.txt                  # dsviper (from PyPI) + GUI/web deps
    ./LICENSE                           # Distribution licensing notice (read first)
    ./LICENSES/MIT.txt                  # MIT — tools, templates, samples, kibo jar
    ./LICENSES/COMMERCIAL.txt           # Digital Substrate Commercial 1.2 — dsviper runtime
    ./DOCUMENTATION.txt                 # Pointers to online doc + offline ZIP/PDF

    ./tools/                            # CLI tools
    ./tools/dsm_util.py                 # DSM Definitions tasks (parse, validate, generate)
    ./tools/commit_admin.py             # CommitDatabase administrative tasks
    ./tools/cdbe.py                     # CommitDatabase Editor (GUI)
    ./tools/dbe.py                      # Database Editor (GUI)
    ./tools/kibo-*.jar                  # Kibo code generator (Java)

    ./templates/python/                 # Python code generation templates

    ./dsm-samples/                      # Reference DSM models (Ge/, Re/, Tuto/)
```

Documentation is published online at https://devkit.digitalsubstrate.io/documentation/
and offered as offline ZIP / PDF on the same site (see DOCUMENTATION.txt for URLs).
IDE extensions live in their own public GitHub repositories (see below).

## Install

### 1. Create a virtual environment

Since Python 3.12 the system installation is often protected
([PEP 668](https://peps.python.org/pep-0668/)):

```bash
python3 -m venv ~/venv
source ~/venv/bin/activate  # macOS/Linux
# or: ~/venv/Scripts/activate  # Windows
```

### 2. Install dependencies

From the extracted DevKit folder, a single command pulls `dsviper` from
PyPI and installs the GUI/web dependencies:

```bash
pip install -r requirements.txt
```

### 3. Verify

```bash
python3 -c "import dsviper; print(dsviper.version())"
```

## Install IDE Extensions

The DSM IDE extensions are distributed via their respective Marketplaces.

### VS Code

Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=DigitalSubstrate.ds-dsm), or in VS Code: `Extensions` → search for "DSM Syntax Highlighter".

Source repository: [github.com/digital-substrate/dsm-vscode](https://github.com/digital-substrate/dsm-vscode)

### JetBrains (IntelliJ, PyCharm, CLion, ...)

Install from the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/com.digitalsubstrate.dsm), or in the IDE: `Settings > Plugins > Marketplace` → search for "DSM".

Source repository: [github.com/digital-substrate/dsm-jetbrains](https://github.com/digital-substrate/dsm-jetbrains)

## DSM Samples

Reference DSM models (graph modeling, 3D rendering) are bundled in this
archive under `./dsm-samples/` (Ge/, Re/, Tuto/) for immediate use with
`dsm_util.py` and the IDE plugins. Upstream source:
[github.com/digital-substrate/dsm-samples](https://github.com/digital-substrate/dsm-samples).

## Web CDBE (demo)

A Flask-based HTML5 Commit Database Editor demonstrating `dsviper` usage
lives in the [web-cdbe](https://github.com/digital-substrate/web-cdbe)
repository:

```bash
git clone https://github.com/digital-substrate/web-cdbe.git
```

## Templated Features

### Templated Features for Python

Content of `templates/python/package/`:

```
    definitions                      # Definitions in the Viper type and value system
    data                             # Classes for concepts, clubs, enumerations, structures
    commit                           # Commit API (class + parameter type hints)
    database                         # Database API (class + parameter type hints)
    value_types                      # Type definitions required by the Data Model
    attachment_function_pools        # Wrapped API for attachment pools
    attachment_function_pools_remote # Wrapped API for remote attachment pools
    function_pools                   # Wrapped API for function pools
    function_pool_remote             # Wrapped API to call remote function pools (Service)
```

Content of `templates/python/wheel/`:

```
    pyproject.toml   # Minimal pyproject.toml to build a wheel
```
