umbi 0.2.4

Library for input/output of transition systems in a unified Markov binary (UMB) format.

umbi

Library for input/output of annotated transition systems (ATSs) in a unified Markov binary (UMB) format. See the format specification for details.

Installation:

pip install umbi

Quick start

A short example where we read a umbfile into an ExplicitAts object, modify initial states, and write it back:

import umbi
ats = umbi.ats.read("in.umb")
ats.set_initial_states([ats.num_states - 1])
umbi.ats.write(ats, "out.umb")

More examples can be found in the ./examples folder.

API

umbi offers multiple levels of abstraction for working with UMB files:

TarFile and TarCoder - low-level access to umbfile contents.

ExplicitUmb - in-memory representation of a typical umbfile. Attributes are standard Python objects (lists, dicts, dataclasses) providing a deserialized view of the file contents.

ExplicitAts - format-agnostic abstraction for annotated transition systems (states, transitions, annotations). Recommended for most use cases: easiest to use programmatically and remains stable across UMB format changes.

CLI

umbi provides a basic CLI for umbfile manipulation.

Options:

• --import-umb <path> - import umbfile as ExplicitUmb
• --import-ats <path> - import umbfile as ExplicitAts
• --export <path> - export to umbfile (requires --import-umb or --import-ats)
• --log-level <LEVEL> - set logging level: DEBUG, INFO (default), WARNING, ERROR, CRITICAL

Example:

umbi --import-umb input.umb --export output.umb --log-level DEBUG

Development

(optional) create and activate a python environment:

python -m venv .venv
source .venv/bin/activate

Setup

Install development dependencies:

pip install .[dev]

Testing

Run the test suite with pytest:

python -m pytest              # run all tests
python -m pytest tests/tar/   # run specific test directory
python -m pytest -k test_name # run tests matching pattern

Current test coverage:

• binary - serialization and binary data handling
• datatypes - data type definitions and conversions
• tar - tarfile I/O and utilities

Code Quality

Pre-commit hooks automatically run code quality checks before each commit. Configuration: .pre-commit-config.yaml

Set up the hooks with:

pre-commit install

Run hooks manually on all files:

pre-commit run --all-files

Individual tools can be run manually:

Ruff -- Code formatting and linting. Config: pyproject.toml ([tool.ruff])

ruff check .       # check for issues
ruff check . --fix # check and fix
ruff format .      # format code

Pyright -- Static type checking. Config: pyproject.toml ([tool.pyright])

pyright             # check entire project
pyright umbi/       # check specific directory

Release

Dependencies are pinned in the uv.lock lockfile for reproducible builds. New versions are published to PyPI via the release workflow. The workflow is triggered automatically when:

• a new version tag is pushed (format: v*.*.*)
• the bump version workflow completes successfully (can be run manually via GitHub actions)

The release workflow:

1. updates the uv.lock lockfile to reflect any dependency changes
2. builds the distribution packages
3. publishes to PyPI via trusted publishing
4. updates the stable branch pointer to track the latest release