Core Utilities¶

Core classes for namespaces, paths, and cross-cutting utilities. Definitions itself is documented with the DSM surface it registers, in DSM & Definitions.

When to use: Use Definitions to register custom types, Path to navigate nested structures, and Logging for debug output.

Quick Start¶

>>> from dsviper import (DSMBuilder, Value, Path, NameSpace, ValueUUId,
...                      LoggerConsole, Logging)

A namespace pairs a UUID with a name:

>>> ns = NameSpace(ValueUUId("f529bc42-0618-4f54-a3fb-d55f95c5ad03"), "MyApp")
>>> ns.name()
'MyApp'

A Path navigates nested structures. Build it, freeze it with const(), then read and write through it:

>>> builder = DSMBuilder()
>>> builder.append("model.dsm", """
... namespace MyApp {8f14e45f-ceea-467a-9575-1c14b48f0b7e} {
...     struct Address { string city; };
...     struct Profile { Address address; uint16 age; };
... };
... """)
>>> report, dsm_defs, defs = builder.parse()
>>> defs.inject(globals())
>>> document = Value.create(MY_APP_S_PROFILE, {"address": {"city": "Lyon"}, "age": 30})

>>> path = Path.from_field("address").field("city").const()
>>> path.representation()
'.address.city'
>>> path.at(document)
'Lyon'
>>> path.set(document, "Paris")
>>> Value.dumps(document)
{'address': {'city': 'Paris'}, 'age': 30}

inject() also emits a constant per path, so the one above is already available as MY_APP_P_PROFILE_ADDRESS.

A logger writes to stderr through its Logging interface:

>>> log = LoggerConsole(Logging.LEVEL_DEBUG).logging()
>>> log.info("Application started")
>>> log.error("Something went wrong")

Key Classes¶

Class	Purpose	Example
`Definitions`	Register custom types	`defs = Definitions()`
`NameSpace`	Group types by namespace	`ns = NameSpace(uuid, "App")`
`Path`	Navigate nested data	`Path.from_field("x").field("y")`
`Logging`	Debug output	`logger.logging().info(msg)`
`Error`	Parse error messages	`Error.parse(str(e))`

Namespace¶

dsviper.NameSpace

A UUID and a name, under which a model's types are registered.

Paths¶

`dsviper.Path`	Constructs the location of a portion of a value.
`dsviper.PathConst`	A finished Path: read or write the value it points at.
`dsviper.PathComponent`	One step of a Path: what kind of step, and the value it carries.
`dsviper.PathElementInfo`	Where an element sits inside a set.
`dsviper.PathEntryKeyInfo`	Where an entry sits inside a map.

Function Pools¶

`dsviper.Function`	A callable C++ function.
`dsviper.FunctionPool`	One pool of C++ functions: its uuid, name and documentation, and the functions it holds - query() by name, funcs for all of them, check() to raise instead of answering None.
`dsviper.FunctionPoolFunctions`	The functions of one pool, reached by attribute.
`dsviper.FunctionPrototype`	The signature of a function: its return type and its parameters.

Hashing¶

`dsviper.Hashing`	An interface to abstract a hasher.
`dsviper.HashCRC32`	Hashes data with CRC32.
`dsviper.HashMD5`	Hashes data with MD5.
`dsviper.HashSHA1`	Hashes data with SHA1.
`dsviper.HashSHA256`	Hashes data with SHA256.
`dsviper.HashSHA3`	Hashes data with SHA3.

Logging¶

`dsviper.Logging`	An interface to emit a message.
`dsviper.LoggerConsole`	Prints a message on the console.
`dsviper.LoggerPrint`	Logs through Python's built-in print, so the output follows sys.stdout and any redirection placed on it.
`dsviper.LoggerReport`	Collects messages instead of emitting them.
`dsviper.LoggerNull`	Discards every message, whatever its level.

Utilities¶

`dsviper.ViperError`	The exception a failing call raises, where Python has no name of its own for it.
`dsviper.Error`	Reads a Viper error: component, domain, code and message.
`dsviper.Cancelation`	A cancellation flag.
`dsviper.Semaphore`	A named semaphore, created or opened by name so that separate processes share it.
`dsviper.SharedMemory`	A named memory region shared between processes.
`dsviper.Socket`	A passive socket for a server: bound by its factory, listened on by the server it is handed to.
`dsviper.Float16`	The 16-bit storage of a float value, converted to and from float.
`dsviper.KeyHelper`	Answers three questions on the key side of a model: which keys of a key type carry a document, which attachments a type is keyed into, and which attachments a given key has no document for.
`dsviper.KeyNamer`	Finds a display name for a key among the attachments that carry one.