better documentation and testing of umbi.tar

Author: randriu

README.md

@@ -105,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]`)

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")
 

tests/tar/test_tar_coder.py

@@ -18,30 +18,31 @@ def test_add_and_read_json(self):
         tc.add_json("data.json", json_obj)
 
         loaded = tc.read_json("data.json")
+        assert loaded is not None
         assert loaded == json_obj
 
     def test_read_json_optional_missing(self):
         """Test reading missing optional JSON file returns None."""
         tc = TarCoder()
-        result = tc.read_json("missing.json", required=False)
+        result = tc.read_json("missing.json", optional=True)
         assert result is None
 
     def test_read_json_required_missing(self):
         """Test reading missing required JSON file raises error."""
         tc = TarCoder()
         with pytest.raises(KeyError):
-            tc.read_json("missing.json", required=True)
+            tc.read_json("missing.json")
 
     def test_add_json_required_none(self):
         """Test that adding None for required JSON raises error."""
         tc = TarCoder()
         with pytest.raises(ValueError):
-            tc.add_json("data.json", None, required=True)
+            tc.add_json("data.json", None)
 
     def test_add_json_optional_none(self):
         """Test that adding None for optional JSON does nothing."""
         tc = TarCoder()
-        tc.add_json("data.json", None, required=False)
+        tc.add_json("data.json", None, optional=True)
         assert not tc.has_file("data.json")
 
     def test_complex_json(self):
@@ -51,6 +52,7 @@ def test_complex_json(self):
 
         tc.add_json("complex.json", json_obj)
         loaded = tc.read_json("complex.json")
+        assert loaded is not None
         assert loaded == json_obj
 
 
@@ -66,14 +68,15 @@ def test_add_and_read_vector(self):
         tc.add_vector("values.bin", sized_type, values)
 
         loaded = tc.read_vector("values.bin", sized_type)
+        assert loaded is not None
         assert loaded == values
 
     def test_read_vector_optional_missing(self):
         """Test reading missing optional vector returns None."""
         tc = TarCoder()
         sized_type = SizedType(NumericPrimitiveType.UINT, 32)
 
-        result = tc.read_vector("missing.bin", sized_type, required=False)
+        result = tc.read_vector("missing.bin", sized_type, optional=True)
         assert result is None
 
     def test_read_vector_required_missing(self):
@@ -82,15 +85,15 @@ def test_read_vector_required_missing(self):
         sized_type = SizedType(NumericPrimitiveType.UINT, 32)
 
         with pytest.raises(KeyError):
-            tc.read_vector("missing.bin", sized_type, required=True)
+            tc.read_vector("missing.bin", sized_type)
 
     def test_add_vector_required_none(self):
         """Test that adding None for required vector raises error."""
         tc = TarCoder()
         sized_type = SizedType(NumericPrimitiveType.UINT, 32)
 
         with pytest.raises(ValueError):
-            tc.add_vector("values.bin", sized_type, None, required=True)
+            tc.add_vector("values.bin", sized_type, None)
 
     def test_vector_roundtrip(self):
         """Test vector round-trip conversion."""
@@ -101,6 +104,7 @@ def test_vector_roundtrip(self):
         tc1.add_vector("data.bin", sized_type, original)
 
         loaded = tc1.read_vector("data.bin", sized_type)
+        assert loaded is not None
         assert loaded == original
 
 
@@ -115,6 +119,7 @@ def test_add_and_read_bitvector(self):
         tc.add_bitvector("bits.bin", bitvector)
 
         loaded = tc.read_bitvector("bits.bin", num_entries=5)
+        assert loaded is not None
         # May be padded, so check the first 5 elements
         assert loaded[:5] == bitvector
 
@@ -127,6 +132,7 @@ def test_bitvector_padding(self):
         tc.add_bitvector("bits.bin", bitvector, pad_to_8_bytes=True)
 
         loaded = tc.read_bitvector("bits.bin", num_entries=5)
+        assert loaded is not None
         assert loaded[:5] == bitvector
         # Remaining should be False (padding)
         assert all(not bit for bit in loaded[5:])
@@ -139,6 +145,7 @@ def test_bitvector_no_padding(self):
         tc.add_bitvector("bits.bin", bitvector, pad_to_8_bytes=False)
 
         loaded = tc.read_bitvector("bits.bin", num_entries=8)
+        assert loaded is not None
         assert loaded == bitvector
 
     def test_bitvector_truncation(self):
@@ -151,10 +158,159 @@ def test_bitvector_truncation(self):
 
         # Read only 8 entries
         loaded = tc.read_bitvector("bits.bin", num_entries=8)
+        assert loaded is not None
         assert len(loaded) == 8
         assert loaded == bitvector[:8]
 
 
+class TestTarCoderVectorWithRanges:
+    """Test vector with CSR ranges reading and writing."""
+
+    def test_add_and_read_vector_with_ranges(self):
+        """Test adding and reading a vector with CSR ranges."""
+        tc = TarCoder()
+        vector = [1, 2, 3, 4, 5, 6, 7, 8]
+        sized_type = SizedType(NumericPrimitiveType.UINT, 32)
+
+        tc.add_vector_with_ranges("data.bin", sized_type, vector, "ranges.bin")
+
+        loaded = tc.read_vector_with_ranges("data.bin", NumericPrimitiveType.UINT, filename_csr="ranges.bin")
+        assert loaded is not None
+        assert loaded == vector
+
+    def test_read_vector_with_ranges_optional_missing(self):
+        """Test reading missing optional vector with ranges returns None."""
+        tc = TarCoder()
+        result = tc.read_vector_with_ranges(
+            "missing.bin", NumericPrimitiveType.UINT, optional=True, filename_csr="ranges.bin"
+        )
+        assert result is None
+
+    def test_read_vector_with_ranges_required_missing(self):
+        """Test reading missing required vector with ranges raises error."""
+        tc = TarCoder()
+        with pytest.raises(KeyError):
+            tc.read_vector_with_ranges("missing.bin", NumericPrimitiveType.UINT, filename_csr="ranges.bin")
+
+    def test_read_vector_with_ranges_missing_csr(self):
+        """Test that missing CSR file raises error even if main file exists."""
+        tc = TarCoder()
+        vector = [1, 2, 3, 4, 5]
+        sized_type = SizedType(NumericPrimitiveType.UINT, 32)
+
+        tc.add_vector_with_ranges("data.bin", sized_type, vector, "ranges.bin")
+        # Remove the CSR file using dict interface
+        tc.pop("ranges.bin", None)
+
+        with pytest.raises(KeyError):
+            tc.read_vector_with_ranges("data.bin", NumericPrimitiveType.UINT, filename_csr="ranges.bin")
+
+    def test_add_vector_with_ranges_required_none(self):
+        """Test that adding None for required vector with ranges raises error."""
+        tc = TarCoder()
+        sized_type = SizedType(NumericPrimitiveType.UINT, 32)
+
+        with pytest.raises(ValueError):
+            tc.add_vector_with_ranges("data.bin", sized_type, None, "ranges.bin")
+
+    def test_add_vector_with_ranges_optional_none(self):
+        """Test that adding None for optional vector with ranges does nothing."""
+        tc = TarCoder()
+        sized_type = SizedType(NumericPrimitiveType.UINT, 32)
+
+        tc.add_vector_with_ranges("data.bin", sized_type, None, "ranges.bin", optional=True)
+        assert not tc.has_file("data.bin")
+        assert not tc.has_file("ranges.bin")
+
+    def test_vector_with_ranges_roundtrip(self):
+        """Test vector with ranges round-trip conversion."""
+        original = [100, 200, 300, 400, 500, 600]
+        sized_type = SizedType(NumericPrimitiveType.UINT, 64)
+
+        tc1 = TarCoder()
+        tc1.add_vector_with_ranges("data.bin", sized_type, original, "ranges.bin")
+
+        loaded = tc1.read_vector_with_ranges("data.bin", NumericPrimitiveType.UINT, filename_csr="ranges.bin")
+        assert loaded is not None
+        assert loaded == original
+
+
+class TestTarCoderStrings:
+    """Test string vector reading and writing with CSR."""
+
+    def test_add_and_read_strings(self):
+        """Test adding and reading strings with CSR."""
+        tc = TarCoder()
+        strings = ["hello", "world", "test", "data"]
+
+        tc.add_strings("strings.bin", strings, "strings_csr.bin")
+
+        loaded = tc.read_strings("strings.bin", filename_csr="strings_csr.bin")
+        assert loaded is not None
+        assert loaded == strings
+
+    def test_read_strings_optional_missing(self):
+        """Test reading missing optional strings returns None."""
+        tc = TarCoder()
+        result = tc.read_strings("missing.bin", optional=True, filename_csr="strings_csr.bin")
+        assert result is None
+
+    def test_read_strings_required_missing(self):
+        """Test reading missing required strings raises error."""
+        tc = TarCoder()
+        with pytest.raises(KeyError):
+            tc.read_strings("missing.bin", filename_csr="strings_csr.bin")
+
+    def test_read_strings_missing_csr(self):
+        """Test that missing CSR file raises error even if main file exists."""
+        tc = TarCoder()
+        strings = ["a", "b", "c"]
+
+        tc.add_strings("strings.bin", strings, "strings_csr.bin")
+        # Remove the CSR file using dict interface
+        tc.pop("strings_csr.bin", None)
+
+        with pytest.raises(KeyError):
+            tc.read_strings("strings.bin", filename_csr="strings_csr.bin")
+
+    def test_add_strings_required_none(self):
+        """Test that adding None for required strings raises error."""
+        tc = TarCoder()
+
+        with pytest.raises(ValueError):
+            tc.add_strings("strings.bin", None, "strings_csr.bin")
+
+    def test_add_strings_optional_none(self):
+        """Test that adding None for optional strings does nothing."""
+        tc = TarCoder()
+
+        tc.add_strings("strings.bin", None, "strings_csr.bin", optional=True)
+        assert not tc.has_file("strings.bin")
+        assert not tc.has_file("strings_csr.bin")
+
+    def test_strings_roundtrip(self):
+        """Test strings round-trip conversion."""
+        original = ["foo", "bar", "baz", "qux", "long string with spaces"]
+
+        tc1 = TarCoder()
+        tc1.add_strings("strings.bin", original, "strings_csr.bin")
+
+        loaded = tc1.read_strings("strings.bin", filename_csr="strings_csr.bin")
+        assert loaded is not None
+        assert loaded == original
+
+    def test_strings_single_empty_string(self):
+        """Test handling of empty strings in list."""
+        tc = TarCoder()
+        strings = ["", "non-empty", ""]
+
+        tc.add_strings("strings.bin", strings, "strings_csr.bin")
+
+        loaded = tc.read_strings("strings.bin", filename_csr="strings_csr.bin")
+        assert loaded is not None
+        assert loaded == strings
+
+
 class TestTarCoderIntegration:
     """Integration tests for TarCoder."""
 
@@ -168,17 +324,23 @@ def test_multiple_files(self):
         tc.add_bitvector("flags.bin", [True, False, True, False])
 
         # Verify all files exist and can be read
-        assert tc.read_json("metadata.json") == {"version": 1}
-        assert tc.read_vector("values.bin", SizedType(NumericPrimitiveType.UINT, 32)) == [1, 2, 3]
-        assert tc.read_bitvector("flags.bin", num_entries=4)[:4] == [True, False, True, False]
+        json_data = tc.read_json("metadata.json")
+        assert json_data is not None
+        assert json_data == {"version": 1}
+        vector_data = tc.read_vector("values.bin", SizedType(NumericPrimitiveType.UINT, 32))
+        assert vector_data is not None
+        assert vector_data == [1, 2, 3]
+        bits_data = tc.read_bitvector("flags.bin", num_entries=4)
+        assert bits_data is not None
+        assert bits_data[:4] == [True, False, True, False]
 
     def test_tar_coder_inherits_tarfile(self):
         """Test that TarCoder has all TarFile functionality."""
         tc = TarCoder()
 
         # Test dict interface
         tc["raw.bin"] = b"raw data"
-        assert tc.get_file("raw.bin") == b"raw data"
+        assert tc.read_file("raw.bin") == b"raw data"
 
         # Test add_file
         tc.add_file("file.bin", b"content")

tests/tar/test_tar_file.py

@@ -23,7 +23,7 @@ def test_add_and_retrieve_file(self):
         tf.add_file("test.txt", data)
 
         assert tf.has_file("test.txt")
-        assert tf.get_file("test.txt") == data
+        assert tf.read_file("test.txt") == data
 
     def test_has_file(self):
         """Test checking if file exists."""
@@ -37,12 +37,12 @@ def test_get_required_file_missing(self):
         """Test that missing required file raises KeyError."""
         tf = TarFile()
         with pytest.raises(KeyError):
-            tf.get_file("missing.txt", required=True)
+            tf.read_file("missing.txt")
 
     def test_get_optional_file_missing(self):
         """Test that missing optional file returns None."""
         tf = TarFile()
-        result = tf.get_file("missing.txt", required=False)
+        result = tf.read_file("missing.txt", optional=True)
         assert result is None
 
     def test_add_file_duplicate_without_overwrite(self):
@@ -59,7 +59,9 @@ def test_add_file_duplicate_with_overwrite(self):
         tf.add_file("file.txt", b"original")
         tf.add_file("file.txt", b"new", overwrite=True)
 
-        assert tf.get_file("file.txt") == b"new"
+        result = tf.read_file("file.txt")
+        assert result is not None
+        assert result == b"new"
 
     def test_filenames_property(self):
         """Test filenames property."""
@@ -92,8 +94,12 @@ def test_write_and_read_tarfile(self, tmp_path: pathlib.Path):
         tf2 = TarFile(tarpath)
         assert tf2.has_file("file1.txt")
         assert tf2.has_file("file2.txt")
-        assert tf2.get_file("file1.txt") == b"content1"
-        assert tf2.get_file("file2.txt") == b"content2"
+        content1 = tf2.read_file("file1.txt")
+        assert content1 is not None
+        assert content1 == b"content1"
+        content2 = tf2.read_file("file2.txt")
+        assert content2 is not None
+        assert content2 == b"content2"
 
     def test_write_and_read_empty_tarfile(self, tmp_path: pathlib.Path):
         """Test writing and reading an empty tarfile."""
@@ -115,7 +121,9 @@ def test_write_with_different_compression(self, tmp_path: pathlib.Path):
             tf.write(tarpath, compression=compression)  # type: ignore
 
             tf_loaded = TarFile(tarpath)
-            assert tf_loaded.get_file("test.txt") == b"data"
+            data = tf_loaded.read_file("test.txt")
+            assert data is not None
+            assert data == b"data"
 
     def test_read_nonexistent_file(self, tmp_path: pathlib.Path):
         """Test that reading nonexistent tarfile raises error."""