refactor umbi.io -> umbi.tar with improved API

- rename umbi.io to umbi.tar
- umbi.tar: flip optional parameter in read_file (new default: mandatory)
- add tar module tests
- fix circular import in ats module
- improve docstrings

Author: randriu

README.md

@@ -1,28 +1,26 @@
 # umbi
 
-Library for input/output of transition systems in a *unified Markov binary (UMB)* format. See the [format specification](https://github.com/pmc-tools/umb/) for details.
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
+[![License MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/umbi)](https://pypi.org/project/umbi/)
+[![Latest Tag](https://img.shields.io/github/tag/pmc-tools/umbi.svg)](https://github.com/pmc-tools/umbi/tags)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/pmc-tools/umbi/test-build.yml)](https://github.com/pmc-tools/umbi/actions)
 
-## Installation:
-
-(optional) create and activate a python environment:
+Library for input/output of annotated transition systems (ATSs) in a *unified Markov binary (UMB)* format. See the [format specification](https://github.com/pmc-tools/umb/) for details.
 
-```bash
-python -m venv .venv
-source .venv/bin/activate
-```
+## Installation:
 
-Install `umbi` via
 ```bash
 pip install umbi
 ```
 
 ## Quick start
 
-Read a umbfile into an `ExplicitAts` object, modify initial states, and write it back:
+A short example where we read a umbfile into an [`ExplicitAts`](umbi/ats/explicit_ats.py) object, modify initial states, and write it back:
 
 ```python
 import umbi
-ats : ExplicitAts = umbi.ats.read("in.umb")
+ats = umbi.ats.read("in.umb")
 ats.set_initial_states([ats.num_states - 1])
 umbi.ats.write(ats, "out.umb")
 ```
@@ -31,23 +29,23 @@ More examples can be found in the [./examples](./examples) folder.
 
 ## API
 
-`umbi` offers three levels of abstraction for working with UMB files:
+`umbi` offers multiple levels of abstraction for working with UMB files:
 
-**[`TarFile`](umbi/io/tar_file.py) and [`TarCoder`](umbi/io/tar_coder.py)** - Low-level access to tarfile contents.
+**[`TarFile`](umbi/tar/tar_file.py) and [`TarCoder`](umbi/tar/tar_coder.py)** - low-level access to umbfile contents.
 
-**[`ExplicitUmb`](umbi/umb/explicit_umb.py)** - In-memory representation of a typical umbfile. Attributes are standard Python objects (lists, dicts, dataclasses) providing a deserialized view of the file contents.
+**[`ExplicitUmb`](umbi/umb/explicit_umb.py)** - in-memory representation of a typical umbfile. Attributes are standard Python objects (lists, dicts, dataclasses) providing a deserialized view of the file contents.
 
-**[`ExplicitAts`](umbi/ats/explicit_ats.py)** - 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.
+**[`ExplicitAts`](umbi/ats/explicit_ats.py)** - 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 .umb file as `ExplicitUmb`
-- `--import-ats <path>` - Import .umb file as `ExplicitAts`
-- `--export <path>` - Export to .umb file (requires `--import-umb` or `--import-ats`)
-- `--log-level <LEVEL>` - Set logging level: `DEBUG`, `INFO` (default), `WARNING`, `ERROR`, `CRITICAL`
+- `--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:**
 ```bash
@@ -56,6 +54,13 @@ umbi --import-umb input.umb --export output.umb --log-level DEBUG
 
 ## Development
 
+(optional) create and activate a python environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
 ### Setup
 
 Install development dependencies:
@@ -64,6 +69,21 @@ Install development dependencies:
 pip install .[dev]
 ```
 
+### Testing
+
+Run the test suite with [pytest](https://pytest.org/):
+
+```bash
+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](.pre-commit-config.yaml)
@@ -85,8 +105,8 @@ Individual tools can be run manually:
 **[Ruff](https://github.com/astral-sh/ruff)** -- Code formatting and linting. Config: [pyproject.toml](pyproject.toml) (`[tool.ruff]`)
 ```bash
 ruff check .       # check for issues
-ruff format .      # format code
 ruff check . --fix # check and fix
+ruff format .      # format code
 ```
 
 **[Pyright](https://github.com/microsoft/pyright)** -- Static type checking. Config: [pyproject.toml](pyproject.toml) (`[tool.pyright]`)
@@ -95,24 +115,14 @@ pyright             # check entire project
 pyright umbi/       # check specific directory
 ```
 
-#### Lockfiles
-
-Dependencies are pinned in the [uv.lock](uv.lock) lockfile for reproducible builds. To update the lockfile:
-
-```bash
-uv lock
-```
-
 ### Release
 
-New versions are published to PyPI via the [release workflow](.github/workflows/release.yml). The workflow is triggered automatically when:
-- A new version tag is pushed (format: `v*.*.*`)
-- The [bump version workflow](.github/workflows/bump.yml) completes successfully
-
-Alternatively, the workflow can be triggered manually via GitHub Actions.
+Dependencies are pinned in the [uv.lock](uv.lock) lockfile for reproducible builds. New versions are published to [PyPI](https://pypi.org/project/umbi/) via the [release workflow](.github/workflows/release.yml). The workflow is triggered automatically when:
+- a new version tag is pushed (format: `v*.*.*`)
+- the [bump version workflow](.github/workflows/bump.yml) completes successfully (can be run manually via GitHub actions)
 
 The release workflow:
-1. Updates the [uv.lock](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
+1. updates the [uv.lock](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

examples/demo/ats.py

@@ -2,6 +2,7 @@
 """Demonstration of umbfile manipulation via ExplicitAts."""
 
 import click
+
 import umbi
 
 

examples/demo/tar.py

@@ -2,6 +2,7 @@
 """Demonstration of tarfile manipulation via TarCoder."""
 
 import click
+
 import umbi
 
 

examples/demo/umb.py

@@ -2,6 +2,7 @@
 """Demonstration of umbfile manipulation via ExplicitUmb."""
 
 import click
+
 import umbi
 
 

examples/misc/ats_smg_to_prism.py

@@ -8,7 +8,6 @@
 import pathlib
 
 import umbi
-import umbi.ats.examples
 
 log = logging.getLogger(__name__)
 
@@ -33,6 +32,7 @@ def ats_smg_to_prism(ats: umbi.ats.ExplicitAts, output_path: pathlib.Path) -> No
         f.write(f"global state: [0..{ats.num_states - 1}];\n\n")
 
         # player declarations
+        player_to_states = None
         if ats.num_players > 0:
             # group states by player
             player_to_states = {}
@@ -60,6 +60,7 @@ def ats_smg_to_prism(ats: umbi.ats.ExplicitAts, output_path: pathlib.Path) -> No
 
         # group states by player for module generation
         if ats.num_players > 0:
+            assert player_to_states is not None
             for player in sorted(player_to_states.keys()):
                 f.write(f"module player{player}\n")
 

pyproject.toml

@@ -73,6 +73,9 @@ exclude = [
 ]
 target-version = "py311"
 
+[tool.ruff.lint]
+select = ["I"]  # enable isort (import sorting) rules
+
 [tool.pyright]
 include = [
   "umbi",

tests/binary/test_numeric_primitive.py

@@ -1,27 +1,28 @@
 """Tests for umbi.binary.numeric_primitive module."""
 
-import pytest
 from fractions import Fraction
+
+import pytest
 from bitstring import BitArray
 
 from umbi.binary.numeric_primitive import (
-    bytes_to_double,
-    double_to_bytes,
     bits_to_double,
-    double_to_bits,
-    bytes_to_integer,
-    integer_to_bytes,
     bits_to_integer,
-    integer_to_bits,
-    bytes_to_rational,
-    rational_to_bytes,
+    bits_to_numeric_primitive,
     bits_to_rational,
-    rational_to_bits,
-    normalize_rational,
+    bytes_to_double,
+    bytes_to_integer,
     bytes_to_numeric_primitive,
-    numeric_primitive_to_bytes,
-    bits_to_numeric_primitive,
+    bytes_to_rational,
+    double_to_bits,
+    double_to_bytes,
+    integer_to_bits,
+    integer_to_bytes,
+    normalize_rational,
     numeric_primitive_to_bits,
+    numeric_primitive_to_bytes,
+    rational_to_bits,
+    rational_to_bytes,
 )
 from umbi.datatypes import NumericPrimitiveType
 

tests/binary/test_primitive.py

@@ -4,14 +4,14 @@
 from bitstring import BitArray
 
 from umbi.binary.primitive import (
-    bool_to_bits,
     bits_to_bool,
+    bits_to_string,
+    bool_to_bits,
     bool_to_bytes,
     bytes_to_bool,
     bytes_to_string,
-    string_to_bytes,
     string_to_bits,
-    bits_to_string,
+    string_to_bytes,
 )
 
 

tests/binary/test_scalar.py

@@ -1,16 +1,17 @@
 """Tests for umbi.binary.scalar module."""
 
-import pytest
 from fractions import Fraction
+
+import pytest
 from bitstring import BitArray
 
-from umbi.binary import scalar_to_bytes, bytes_to_scalar
+from umbi.binary import bytes_to_scalar, scalar_to_bytes
 from umbi.binary.scalar import bits_to_scalar, scalar_to_bits
 from umbi.datatypes import (
-    PrimitiveType,
-    NumericPrimitiveType,
     Interval,
     IntervalType,
+    NumericPrimitiveType,
+    PrimitiveType,
 )
 
 

tests/binary/test_sequence.py

@@ -3,16 +3,15 @@
 import pytest
 
 from umbi.binary import (
+    BOOL1,
+    UINT32,
+    SizedType,
     bytes_to_vector,
-    vector_to_bytes,
     bytes_with_ranges_to_vector,
+    vector_to_bytes,
     vector_to_bytes_with_ranges,
-    SizedType,
-    BOOL1,
-    UINT32,
 )
-from umbi.datatypes import PrimitiveType, NumericPrimitiveType
-from umbi.io.utils import csr_to_ranges
+from umbi.datatypes import NumericPrimitiveType, PrimitiveType
 
 
 class TestBytesToBitvector:
@@ -141,8 +140,6 @@ def test_vector_to_bytes_with_ranges(self):
         bytes_data, chunk_csr = vector_to_bytes_with_ranges(values, sized_type, little_endian=True)
         assert chunk_csr is not None
         assert len(bytes_data) == 12  # 3 * 4 bytes
-        chunk_ranges = csr_to_ranges(chunk_csr)
-        assert len(chunk_ranges) == 3  # 3 values
 
     def test_ranges_roundtrip(self):
         """Test round-trip with ranges."""
@@ -151,7 +148,8 @@ def test_ranges_roundtrip(self):
 
         bytes_data, chunk_csr = vector_to_bytes_with_ranges(original, sized_type, little_endian=True)
         assert chunk_csr is not None
-        chunk_ranges = csr_to_ranges(chunk_csr)
+        # For 3 values of 4 bytes each: ranges are (0,4), (4,8), (8,12)
+        chunk_ranges = [(0, 4), (4, 8), (8, 12)]
         result = bytes_with_ranges_to_vector(bytes_data, sized_type.type, chunk_ranges, little_endian=True)
 
         assert result == original