itf-py 0.2.2__tar.gz → 0.4.0__tar.gz

{itf_py-0.2.2 → itf_py-0.4.0}/PKG-INFO

@@ -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/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.2.2 → itf_py-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "itf-py"
-version = "0.2.2"
+version = "0.4.0"
 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>"]
@@ -11,7 +11,6 @@ packages = [{include = "itf_py", from = "src"}]
 [tool.poetry.dependencies]
 python = "^3.12"
 frozendict = "^2.4.6"
-frozenlist = "^1.7.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0.0"

{itf_py-0.2.2 → itf_py-0.4.0}/src/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-0.4.0/src/itf_py/itf.py

@@ -0,0 +1,188 @@
+from collections import namedtuple
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, NoReturn, Optional, SupportsIndex
+
+from frozendict import frozendict
+
+
+@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, 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(...)
+                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):
+        return ImmutableList([value_from_json(v) for v in val])
+    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, 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.
+        return {k: value_to_json(v) for k, v in val.__dict__.items()}
+    elif isinstance(val, tuple) and hasattr(val, "_fields"):
+        # namedtuple
+        return {k: value_to_json(v) for k, v in val._asdict().items()}  # type: ignore
+    elif isinstance(val, str):
+        return val
+    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

itf_py-0.2.2/README.md

@@ -1,10 +0,0 @@
-# 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).
-
-**Intentionally minimalistic.** We keep this library intentionally minimalistic.
-You can use it in your projects without worrying about pulling dozens of
-dependencies.

itf_py-0.2.2/src/itf_py/itf.py

@@ -1,117 +0,0 @@
-from collections import namedtuple
-from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
-
-from frozendict import frozendict
-from frozenlist import FrozenList
-
-
-@dataclass
-class ITFState:
-    """A single state in an ITF trace as a Python object."""
-
-    meta: Dict[str, Any]
-    values: Dict[str, Any]
-
-
-@dataclass
-class ITFTrace:
-    """An ITF trace as a Python object."""
-
-    meta: Dict[str, Any]
-    params: List[str]
-    vars: List[str]
-    states: List[ITFState]
-    loop: Optional[int]
-
-
-@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, 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 frozendict(d)  # immutable dictionary
-        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()})
-    elif isinstance(val, list):
-        lst = FrozenList([value_from_json(v) for v in val])
-        lst.freeze()  # make it immutable
-        return lst
-    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, 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) or isinstance(val, FrozenList):
-        return [value_to_json(v) for v in val]
-    elif hasattr(val, "__dict__"):
-        return {k: value_to_json(v) for k, v in val.__dict__.items()}
-    elif isinstance(val, tuple) and hasattr(val, "_fields"):
-        # namedtuple
-        return {k: value_to_json(v) for k, v in val._asdict().items()}  # type: ignore
-    elif isinstance(val, str):
-        return val
-    else:
-        return ITFUnserializable(value=str(val))
-
-
-def state_from_json(raw_state: Dict[str, Any]) -> ITFState:
-    """Deserialize a single ITFState 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)
-
-
-def state_to_json(state: ITFState) -> Dict[str, Any]:
-    """Serialize a single ITFState 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"""
-    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)
-
-
-def trace_to_json(trace: ITFTrace) -> Dict[str, Any]:
-    """Serialize an ITFTrace 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