Getting started with dsm_util.py

dsm_utils.py is a tool to handle common tasks with DSM Definitions files.

Reading the source code of the tool is a good introduction to dsviper and kibo.

The dsm_util.py sub-commands are:

  • check: Check syntax of DSM Definitions.
  • create_commit_database: Create a Commit database.
  • create_database: Create a database.
  • create_python_package: Generate a Python package.
  • encode: Encode DSM definitions to the binary format.
  • decode: Decode DSM Definitions from the binary format.

The input data model is a file of DSM Definitions or a folder of DSM_Definitions files. The extension commonly used is .dsm for file encoded in UTF-8 and .dsmb for the binary format.

All sub-commands start by checking the DSM Definitions.

Check DSM syntax

Check and report errors with the format <file>:<line>:<column>:<message>.

> dsm_util.py check model.dsm

for a folder '../definitions/Raptor'.

> dsm_util.py check ../definitions/Raptor

Plausible reported errors for a data model:

model.dsm:10:5: The type 'strin' is unknown.
model.dsm:14:12: The type K='user' in attachment<K, D> 'identity' must be a concept, a club or any_concept.

Create a Commit database

Create an empty Commit database and extends the embedded Definitions with the DSM Definitions from model.dsm.

> dsm_util.py create_commit_database model.dsm model.cdb

You can use any file extension since the type of the database (CommitDatabase or Database) is checked at runtime.

Create a database

Create an empty database and extends the embedded definitions with the DSM Definitions from model.dsm.

> dsm_util.py create_database model.dsm model.db

Create a Python package

Create a python package in the folder <model> from a file <model>.dsm or a folder of dsm file <model>/

The features of the generated module are:

  • \.definitions: The Definitions expressed for the Viper type system.
  • \.data: Classes for all concepts, clubs, enumerations and structures.
  • \.commit: The Commit API with a class and parameter type hint.
  • \.database: The Database API with class and parameters type hint.
  • \.value_types: The definitions of all types required by the data model.
  • ...
> dsm_util.py create_python_package model.dsm --repos /Volumes/DigitalSubstrate

For a wheel, use --wheel to create a default pyproject.toml and then generate the wheel.

You must edit pyproject.toml for a public distribution by adding a section, author, maintainer, license...

> dsm_util.py create_model --wheel model.dsm 
> python3 -m pip wheel .
> python3 -m pip install --force-reinstall model-1.0.0-py3-none-any.whl

Encode DSM Definitions

Encode the DSM Definitions to the binary format used by external tools.

> dsm_util.py encode model.dsm model.dsmb

decode a .dsmb file

Decode the DSM Definitions from the binary format.

> dsm_util.py decode model.dsmb decoded_model.dsm