itf-py 0.4.3__tar.gz

itf_py-0.4.3/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: itf-py
+Version: 0.4.3
+Summary: Python library to parse and emit Apalache/Quint traces in ITF JSON
+Keywords: itf,trace,parser,tlaplus,apalache,quint
+Author: Igor Konnov
+Author-email: igor@konnov.phd
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: frozendict (>=2.4.6,<3.0.0)
+Project-URL: Homepage, https://github.com/konnov/itf-py
+Description-Content-Type: text/markdown
+
+# ITF-py: Parser and Encoder for the ITF Trace Format
+
+Python library to parse and emit Apalache ITF traces. Refer to [ADR015][] for
+the format. ITF traces are emitted by [Apalache][] and [Quint][].
+
+**Intentionally minimalistic.** We keep this library intentionally minimalistic.
+You can use it in your projects without worrying about pulling dozens of
+dependencies. The package depends on `frozendict`.
+
+**Why?** It's much more convenient to manipulate with trace data in an
+interactive prompt, similar to SQL.
+
+See usage examples on the [itf-py][] page on Github.
+
+**Alternatives.** If you need to deserialize/serialize ITF traces in Rust, check
+[itf-rs][].
+
+[ADR015]: https://apalache-mc.org/docs/adr/015adr-trace.html
+[Apalache]: https://github.com/apalache-mc/apalache
+[Quint]: https://github.com/informalsystems/quint
+[itf-rs]: https://github.com/informalsystems/itf-rs
+[itf-py]: https://github.com/konnov/itf-py

itf_py-0.4.3/README.md

@@ -0,0 +1,22 @@
+# ITF-py: Parser and Encoder for the ITF Trace Format
+
+Python library to parse and emit Apalache ITF traces. Refer to [ADR015][] for
+the format. ITF traces are emitted by [Apalache][] and [Quint][].
+
+**Intentionally minimalistic.** We keep this library intentionally minimalistic.
+You can use it in your projects without worrying about pulling dozens of
+dependencies. The package depends on `frozendict`.
+
+**Why?** It's much more convenient to manipulate with trace data in an
+interactive prompt, similar to SQL.
+
+See usage examples on the [itf-py][] page on Github.
+
+**Alternatives.** If you need to deserialize/serialize ITF traces in Rust, check
+[itf-rs][].
+
+[ADR015]: https://apalache-mc.org/docs/adr/015adr-trace.html
+[Apalache]: https://github.com/apalache-mc/apalache
+[Quint]: https://github.com/informalsystems/quint
+[itf-rs]: https://github.com/informalsystems/itf-rs
+[itf-py]: https://github.com/konnov/itf-py

itf_py-0.4.3/pyproject.toml

@@ -0,0 +1,86 @@
+[tool.poetry]
+name = "itf-py"
+version = "0.4.3"
+description = "Python library to parse and emit Apalache/Quint traces in ITF JSON"
+homepage = "https://github.com/konnov/itf-py"
+authors = ["Igor Konnov <igor@konnov.phd>"]
+readme = "README.md"
+keywords = ["itf", "trace", "parser", "tlaplus", "apalache", "quint"]
+packages = [{include = "itf_py", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+frozendict = "^2.4.6"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-cov = "^5.0.0"
+black = "^24.0.0"
+isort = "^5.13.0"
+flake8 = "^7.0.0"
+mypy = "^1.8.0"
+markdown-pytest = "^0.3.2"
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 88
+target-version = ['py312']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+line_length = 88
+known_first_party = ["itf_py"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "--strict-markers --strict-config --verbose"
+
+[tool.flake8]
+max-line-length = 88
+extend-ignore = ["E203", "W503"]
+exclude = [
+    ".git",
+    "__pycache__",
+    ".venv",
+    ".eggs",
+    "*.egg",
+    "dist",
+    "build",
+]

itf_py-0.4.3/src/itf_py/__init__.py

@@ -0,0 +1,28 @@
+"""
+Python library to parse and emit Apalache ITF traces.
+"""
+
+from .itf import (
+    State,
+    Trace,
+    itf_variant,
+    state_from_json,
+    state_to_json,
+    trace_from_json,
+    trace_to_json,
+    value_from_json,
+    value_to_json,
+)
+
+__version__ = "0.2.1"
+__all__ = [
+    "State",
+    "Trace",
+    "itf_variant",
+    "state_from_json",
+    "state_to_json",
+    "trace_from_json",
+    "trace_to_json",
+    "value_from_json",
+    "value_to_json",
+]

itf_py-0.4.3/src/itf_py/itf.py

@@ -0,0 +1,255 @@
+from collections import namedtuple
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, NoReturn, Optional, SupportsIndex
+
+from frozendict import frozendict
+
+
+def itf_variant(cls):  # type: ignore[no-untyped-def]
+    """Decorator to mark a class as an ITF variant type as opposed to a record."""
+
+    cls._itf_variant = True
+    return cls
+
+
+@dataclass
+class State:
+    """A single state in an ITF trace as a Python object."""
+
+    meta: Dict[str, Any]
+    values: Dict[str, Any]
+
+
+@dataclass
+class Trace:
+    """An ITF trace as a Python object."""
+
+    meta: Dict[str, Any]
+    params: List[str]
+    vars: List[str]
+    states: List[State]
+    loop: Optional[int]
+
+
+class ImmutableList(list):
+    """An immutable wrapper around list that supports hashing,
+    yet displays as a list."""
+
+    # frozenlist.FrozenList is what we want, but it does not display
+    # nicely in pretty-printing.
+
+    def __init__(self, items: Iterable[Any]):
+        super().__init__(items)
+
+    def __hash__(self) -> int:  # type: ignore
+        return hash(tuple(self))
+
+    def _forbid_modification(self) -> NoReturn:
+        """Forbid modification of the list."""
+        raise TypeError("This list is immutable and cannot be modified.")
+
+    def __setitem__(self, _key: Any, _value: Any) -> NoReturn:
+        self._forbid_modification()
+
+    def __delitem__(self, _key: Any) -> NoReturn:
+        self._forbid_modification()
+
+    def append(self, _value: Any) -> NoReturn:
+        self._forbid_modification()
+
+    def extend(self, _values: Iterable[Any]) -> NoReturn:
+        self._forbid_modification()
+
+    def insert(self, _index: SupportsIndex, _value: Any) -> None:
+        self._forbid_modification()
+
+    def pop(self, _index: SupportsIndex = -1) -> NoReturn:
+        self._forbid_modification()
+
+    def remove(self, _value: Any) -> NoReturn:
+        self._forbid_modification()
+
+    def clear(self) -> NoReturn:
+        self._forbid_modification()
+
+    def reverse(self) -> NoReturn:
+        self._forbid_modification()
+
+
+class ImmutableDict(frozendict):
+    """A wrapper around frozendict that displays dictionaries as
+    `{k1: v_1, ..., k_n: v_n}`."""
+
+    def __new__(cls, items: Dict[str, Any]) -> Any:
+        return super().__new__(cls, items)
+
+
+ImmutableDict.__str__ = (  # type: ignore
+    dict.__str__
+)  # use the default dict representation in pretty-printing
+
+ImmutableDict.__repr__ = (  # type: ignore
+    dict.__repr__
+)  # use the default dict representation in pretty-printing
+
+
+@dataclass
+class ITFUnserializable:
+    """A placeholder for unserializable values."""
+
+    value: str
+
+
+def value_from_json(val: Any) -> Any:
+    """Deserialize a Python value from JSON"""
+    if isinstance(val, list):
+        return ImmutableList([value_from_json(v) for v in val])
+    elif isinstance(val, dict):
+        if "#bigint" in val:
+            return int(val["#bigint"])
+        elif "#tup" in val:
+            return tuple(value_from_json(v) for v in val["#tup"])
+        elif "#set" in val:
+            return frozenset(value_from_json(v) for v in val["#set"])
+        elif "#map" in val:
+            d = {value_from_json(k): value_from_json(v) for (k, v) in val["#map"]}
+            return ImmutableDict(d)
+        elif "#unserializable" in val:
+            return ITFUnserializable(value=val["#unserializable"])
+        else:
+            ks = val.keys()
+            if len(ks) == 2 and "tag" in ks and "value" in ks:
+                # This is a tagged union, e.g., {"tag": "Banana", "value": {...}}.
+                # Produce Banana(...)
+                value_field = val["value"]
+                if isinstance(value_field, dict):
+                    # The value is a record: {"tag": "Banana", "value": {"length": 5}}
+                    # Decorate it with @itf_variant.
+                    union_type_record = itf_variant(
+                        namedtuple(val["tag"], value_field.keys())
+                    )
+                    return union_type_record(
+                        **{k: value_from_json(v) for k, v in value_field.items()}
+                    )
+                else:
+                    # The value is a scalar: {"tag": "Banana", "value": "u_OF_UNIT"}
+                    # Decorate it with @itf_variant.
+                    union_type_scalar = itf_variant(namedtuple(val["tag"], ["value"]))
+                    return union_type_scalar(value=value_from_json(value_field))
+            else:
+                # This is a general record, e.g., {"field1": ..., "field2": ...}.
+                rec_type = namedtuple("Rec", list(val.keys()))  # type: ignore[misc]
+                return rec_type(**{k: value_from_json(v) for k, v in val.items()})
+    else:
+        return val  # int, str, bool
+
+
+def value_to_json(val: Any) -> Any:
+    """Serialize a Python value into JSON"""
+    if isinstance(val, bool):
+        return val
+    elif isinstance(val, str):
+        return val
+    elif isinstance(val, int):
+        return {"#bigint": str(val)}
+    elif isinstance(val, tuple) and not hasattr(val, "_fields"):
+        return {"#tup": [value_to_json(v) for v in val]}
+    elif isinstance(val, frozenset):
+        return {"#set": [value_to_json(v) for v in val]}
+    elif isinstance(val, dict):
+        return {"#map": [[value_to_json(k), value_to_json(v)] for k, v in val.items()]}
+    elif isinstance(val, list):
+        return [value_to_json(v) for v in val]
+    elif hasattr(val, "__dict__"):
+        # An object-like structure, e.g., a record, or a union.
+        # Note that we cannot distinguish between a record and a tagged union here.
+        if not hasattr(val.__class__, "_itf_variant"):
+            return {k: value_to_json(v) for k, v in val.__dict__.items()}
+        else:
+            # This is a tagged union
+            tag_name = val.__class__.__name__
+            fields_dict = val.__dict__
+            if len(fields_dict) == 0:
+                # No fields: {"tag": "Banana", "value": null}
+                return {
+                    "tag": tag_name,
+                    "value": None,
+                }
+            elif list(fields_dict.keys()) == ["value"]:
+                # Single field named "value": {"tag": "Banana", "value": ...}
+                return {
+                    "tag": tag_name,
+                    "value": value_to_json(fields_dict["value"]),
+                }
+            else:
+                # Multiple fields or a non-value field:
+                #   {"tag": "Banana", "value": {...}}
+                return {
+                    "tag": tag_name,
+                    "value": {k: value_to_json(v) for k, v in fields_dict.items()},
+                }
+    elif isinstance(val, tuple) and hasattr(val, "_fields"):
+        if not hasattr(val.__class__, "_itf_variant"):
+            # Regular record
+            fields_dict = val._asdict()  # type: ignore[attr-defined]
+            return {k: value_to_json(v) for k, v in fields_dict.items()}
+        else:
+            # This is a tagged union
+            tag_name = val.__class__.__name__
+            fields_dict = val._asdict()  # type: ignore[attr-defined]
+            if len(fields_dict) == 0:
+                # No fields: {"tag": "Banana", "value": null}
+                return {
+                    "tag": tag_name,
+                    "value": None,
+                }
+            elif list(fields_dict.keys()) == ["value"]:
+                # Single field named "value": {"tag": "Banana", "value": ...}
+                return {
+                    "tag": tag_name,
+                    "value": value_to_json(fields_dict["value"]),
+                }
+            else:
+                # Multiple fields or a non-value field:
+                #   {"tag": "Banana", "value": {...}}
+                return {
+                    "tag": tag_name,
+                    "value": {k: value_to_json(v) for k, v in fields_dict.items()},
+                }
+    else:
+        return ITFUnserializable(value=str(val))
+
+
+def state_from_json(raw_state: Dict[str, Any]) -> State:
+    """Deserialize a single State from JSON"""
+    state_meta = raw_state["#meta"] if "#meta" in raw_state else {}
+    values = {k: value_from_json(v) for k, v in raw_state.items() if k != "#meta"}
+    return State(meta=state_meta, values=values)
+
+
+def state_to_json(state: State) -> Dict[str, Any]:
+    """Serialize a single State to JSON"""
+    result = {"#meta": state.meta}
+    for k, v in state.values.items():
+        result[k] = value_to_json(v)
+    return result
+
+
+def trace_from_json(data: Dict[str, Any]) -> Trace:
+    """Deserialize a Trace from JSON"""
+    meta = data["#meta"] if "#meta" in data else {}
+    params = data.get("params", [])
+    vars_ = data["vars"]
+    loop = data.get("loop", None)
+    states = [state_from_json(s) for s in data["states"]]
+    return Trace(meta=meta, params=params, vars=vars_, states=states, loop=loop)
+
+
+def trace_to_json(trace: Trace) -> Dict[str, Any]:
+    """Serialize a Trace to JSON"""
+    result: Dict[str, Any] = {"#meta": trace.meta}
+    result["params"] = trace.params
+    result["vars"] = trace.vars
+    result["loop"] = trace.loop
+    result["states"] = [state_to_json(s) for s in trace.states]
+    return result