itf-py 0.2.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

itf_py/__init__.py

@@ -3,8 +3,8 @@ Python library to parse and emit Apalache ITF traces.
 """
 
 from .itf import (
-    ITFState,
-    ITFTrace,
+    State,
+    Trace,
     state_from_json,
     state_to_json,
     trace_from_json,
@@ -15,8 +15,8 @@ from .itf import (
 
 __version__ = "0.2.1"
 __all__ = [
-    "ITFState",
-    "ITFTrace",
+    "State",
+    "Trace",
     "value_to_json",
     "value_from_json",
     "state_to_json",

itf_py/itf.py

@@ -1,13 +1,12 @@
 from collections import namedtuple
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, Iterable, List, NoReturn, Optional, SupportsIndex
 
 from frozendict import frozendict
-from frozenlist import FrozenList
 
 
 @dataclass
-class ITFState:
+class State:
     """A single state in an ITF trace as a Python object."""
 
     meta: Dict[str, Any]
@@ -15,16 +14,78 @@ class ITFState:
 
 
 @dataclass
-class ITFTrace:
+class Trace:
     """An ITF trace as a Python object."""
 
     meta: Dict[str, Any]
     params: List[str]
     vars: List[str]
-    states: List[ITFState]
+    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."""
@@ -43,16 +104,24 @@ def value_from_json(val: Any) -> Any:
             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 frozendict(d)  # immutable dictionary
+            return ImmutableDict(d)
         elif "#unserializable" in val:
             return ITFUnserializable(value=val["#unserializable"])
         else:
-            tup_type = namedtuple("ITFRecord", val.keys())  # type: ignore
-            return tup_type(**{k: value_from_json(v) for k, v in val.items()})
+            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(...)
+                union_type = namedtuple(val["tag"], val["value"].keys())  # type: ignore
+                return union_type(
+                    **{k: value_from_json(v) for k, v in val["value"].items()}
+                )
+            else:
+                # This is a general record, e.g., {"field1": ..., "field2": ...}.
+                rec_type = namedtuple("Rec", val.keys())  # type: ignore
+                return rec_type(**{k: value_from_json(v) for k, v in val.items()})
     elif isinstance(val, list):
-        lst = FrozenList([value_from_json(v) for v in val])
-        lst.freeze()  # make it immutable
-        return lst
+        return ImmutableList([value_from_json(v) for v in val])
     else:
         return val  # int, str, bool
 
@@ -69,9 +138,11 @@ def value_to_json(val: Any) -> Any:
         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) or isinstance(val, FrozenList):
+    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.
         return {k: value_to_json(v) for k, v in val.__dict__.items()}
     elif isinstance(val, tuple) and hasattr(val, "_fields"):
         # namedtuple
@@ -82,33 +153,33 @@ def value_to_json(val: Any) -> Any:
         return ITFUnserializable(value=str(val))
 
 
-def state_from_json(raw_state: Dict[str, Any]) -> ITFState:
-    """Deserialize a single ITFState from JSON"""
+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 ITFState(meta=state_meta, values=values)
+    return State(meta=state_meta, values=values)
 
 
-def state_to_json(state: ITFState) -> Dict[str, Any]:
-    """Serialize a single ITFState to JSON"""
+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]) -> ITFTrace:
-    """Deserialize an ITFTrace from JSON"""
+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 ITFTrace(meta=meta, params=params, vars=vars_, states=states, loop=loop)
+    return Trace(meta=meta, params=params, vars=vars_, states=states, loop=loop)
 
 
-def trace_to_json(trace: ITFTrace) -> Dict[str, Any]:
-    """Serialize an ITFTrace to JSON"""
+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

{itf_py-0.2.2.dist-info → itf_py-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: itf-py
-Version: 0.2.2
+Version: 0.4.0
 Summary: Python library to parse and emit Apalache/Quint traces in ITF JSON
 Keywords: itf,trace,parser,tlaplus,apalache,quint
 Author: Igor Konnov
@@ -10,17 +10,28 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: frozendict (>=2.4.6,<3.0.0)
-Requires-Dist: frozenlist (>=1.7.0,<2.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](https://apalache-mc.org/docs/adr/015adr-trace.html) for the format. ITF
-traces are emitted by [Apalache](https://github.com/apalache-mc/apalache) and
-[Quint](https://github.com/informalsystems/quint).
+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.
+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.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+itf_py/__init__.py,sha256=Mt8_Bce40YIC0PRZik2MN-IH7Ro6GsK69EuQUsU-leo,421
+itf_py/itf.py,sha256=utBjWrN_rO4AGOtSBsD0Wa-nLH9OgMnlGqcpCuULCio,6289
+itf_py-0.4.0.dist-info/METADATA,sha256=zcGdqS3KhL8DxiL_72HCBkI_1p6ZW2I8N_7pg-raD04,1465
+itf_py-0.4.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+itf_py-0.4.0.dist-info/RECORD,,

itf_py-0.2.2.dist-info/RECORD

@@ -1,5 +0,0 @@
-itf_py/__init__.py,sha256=hGN4R5969esBx4T9Cy5sIO7EP3QWiWra3_DhkmbKaso,433
-itf_py/itf.py,sha256=tiZR3g3-HRoDNk7eH26M7hxVyK3tMVGXhxsUxw-PCrQ,3934
-itf_py-0.2.2.dist-info/METADATA,sha256=h-fmihrktQZuM9g03H_3QYwWPAtJYHQWBO1FAWKWl-4,1085
-itf_py-0.2.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-itf_py-0.2.2.dist-info/RECORD,,