openprocess 0.10.6__tar.gz → 0.11.0__tar.gz

{openprocess-0.10.6/openprocess.egg-info → openprocess-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openprocess
-Version: 0.10.6
+Version: 0.11.0
 Summary: Process mining, Petri nets and workflows in one open app: every algorithm visible, every result reproducible, every step teachable
 Author: Sam Struthers
 License: MIT
@@ -528,17 +528,19 @@ links to the definitions it builds on; **Help ▸ Definitions** lists them all.
   for bounded nets; for unbounded ones, up to a trace length (and it says
   so).
 
-| Process map | Discovering a model |
+| Process map | Discover in Mine →: the miner is a box, its result beside the canvas |
 |---|---|
 | ![Process map](docs/screenshots/studio-process-map.png) | ![Discover](docs/screenshots/studio-discover.png) |
 
-| α-algorithm result | Conformance (alignments on the model) |
+| α-algorithm result | *How*: the eight steps, from the footprint to α(L) |
 |---|---|
-| ![Alpha](docs/screenshots/studio-alpha.png) | ![Conformance](docs/screenshots/studio-conformance.png) |
+| ![Alpha](docs/screenshots/studio-alpha.png) | ![The eight steps of the α-algorithm](docs/screenshots/studio-alpha-how.png) |
 
-| Comparing two logs | Linked dotted charts of three boarding strategies |
+| Check fit: every score, and how it was computed | Comparing two logs |
 |---|---|
-| ![Comparing two logs](docs/screenshots/compare.png) | ![Linked dotted charts](docs/screenshots/compare-dotted.png) |
+| ![Conformance](docs/screenshots/studio-conformance.png) | ![Comparing two logs](docs/screenshots/compare.png) |
+
+![Linked dotted charts of two logs, one scale and one colour per activity](docs/screenshots/compare-dotted.png)
 
 The app follows the system's light or dark appearance:
 
@@ -555,6 +557,8 @@ sidebar, **Learn ▸ Open Exercise Pack…**, or **Learn ▸ Open Demo Exercises
 exercises): the window switches to a view made for working through a pack
 without distractions, and *Exit* brings your folder back exactly as it was.
 
+![An exercise in Learn: the worksheet with its answer boxes on the left, the exercise's log, given net and workflow on the right](docs/screenshots/learn-exercise.png)
+
 - **The worksheet** on the left is the question top to bottom, with an
   answer box wherever one is needed: yes/no, multiple choice, a set
   (`{a, b}`, sets of sets, or pairs like `({a}, {b,d})`), a number, a short
@@ -742,7 +746,10 @@ generated from `openprocess/mining/definitions.py`; after editing a definition,
 Likewise [`docs/references.md`](docs/references.md) — every source OpenProcess's
 notation and algorithms follow, also in the app under **Help ▸ References** —
 is generated from `openprocess/references.py` with
-`python -m openprocess.references > docs/references.md`.
+`python -m openprocess.references > docs/references.md`. The screenshots in
+this README come from the app itself: `python docs/make_screenshots.py`
+renders every page offscreen into `docs/screenshots/`, so run it after a
+change to the app's looks.
 
 The engines (`openprocess.mining`, `openprocess.ml`, `openprocess.sim`, `openprocess.analysis`)
 have **no dependencies**, so they work in a notebook or a script:
@@ -769,6 +776,10 @@ Miner, a fitness check), *Compare discovery* (three miners side by side),
 confidence* (bootstrap intervals, a test and a plot; needs the `science`
 extra) and *Predict the next activity*. Or start empty.
 
+| The canvas: *Compare discovery*, three miners side by side | Summary: every box's key figure, and the process map |
+|---|---|
+| ![The canvas of a Compare discovery analysis, the Compare box's table beside it](docs/screenshots/workflow-canvas.png) | ![The Summary view: a tile per box, the process map under them](docs/screenshots/workflow-summary.png) |
+
 - **The page is the canvas.** Its header has **Canvas | Summary**, then
   **+ Add box**, **Run ▶**, and **⋯** for Re-run, Record, Export experiment
   and Save. The sidebar beside it lists the folder's analyses and, folded
@@ -825,8 +836,18 @@ extra) and *Predict the next activity*. Or start empty.
   `boxes/`, so it is listed under *Yours* and can be used in any workflow.
 - **Export experiment** (under ⋯) writes a zip with the workflow file and its record,
   the inputs, your boxes, every result as a file (CSV, PNML, SVG, XES), a
-  `requirements.lock` and a README that says what was run: supplementary
-  material for a paper, which `openprocess run --check` can verify.
+  `requirements.lock`, a `run.py` that runs the same analysis as a plain
+  script, and a README that says what was run: supplementary material for a
+  paper, which `openprocess run --check` can verify. Drop such a zip on
+  OpenProcess and it is unpacked into a folder of its own and run again.
+- **Export as Python script** (under ⋯) writes the analysis as a `.py` file:
+  the same boxes, settings and connections, run with `python analysis.py`,
+  the results written beside it.
+- **Every result knows where it came from**: a figure saved as SVG carries
+  the analysis, the box, its settings and the result's fingerprint in its
+  metadata; a CSV gets a `.provenance.json` beside it.
+- **⌘Z and ⇧⌘Z** undo and redo on the canvas: boxes, connections, moves,
+  settings, groups.
 - **The side panel** resizes by dragging the gap beside it; double-click the
   gap, or *View ▸ Reset Workflow Layout*, for its default width.
 - **Connections** (at the bottom of the sidebar, or *View ▸ Connections*)

{openprocess-0.10.6 → openprocess-0.11.0}/README.md

@@ -489,17 +489,19 @@ links to the definitions it builds on; **Help ▸ Definitions** lists them all.
   for bounded nets; for unbounded ones, up to a trace length (and it says
   so).
 
-| Process map | Discovering a model |
+| Process map | Discover in Mine →: the miner is a box, its result beside the canvas |
 |---|---|
 | ![Process map](docs/screenshots/studio-process-map.png) | ![Discover](docs/screenshots/studio-discover.png) |
 
-| α-algorithm result | Conformance (alignments on the model) |
+| α-algorithm result | *How*: the eight steps, from the footprint to α(L) |
 |---|---|
-| ![Alpha](docs/screenshots/studio-alpha.png) | ![Conformance](docs/screenshots/studio-conformance.png) |
+| ![Alpha](docs/screenshots/studio-alpha.png) | ![The eight steps of the α-algorithm](docs/screenshots/studio-alpha-how.png) |
 
-| Comparing two logs | Linked dotted charts of three boarding strategies |
+| Check fit: every score, and how it was computed | Comparing two logs |
 |---|---|
-| ![Comparing two logs](docs/screenshots/compare.png) | ![Linked dotted charts](docs/screenshots/compare-dotted.png) |
+| ![Conformance](docs/screenshots/studio-conformance.png) | ![Comparing two logs](docs/screenshots/compare.png) |
+
+![Linked dotted charts of two logs, one scale and one colour per activity](docs/screenshots/compare-dotted.png)
 
 The app follows the system's light or dark appearance:
 
@@ -516,6 +518,8 @@ sidebar, **Learn ▸ Open Exercise Pack…**, or **Learn ▸ Open Demo Exercises
 exercises): the window switches to a view made for working through a pack
 without distractions, and *Exit* brings your folder back exactly as it was.
 
+![An exercise in Learn: the worksheet with its answer boxes on the left, the exercise's log, given net and workflow on the right](docs/screenshots/learn-exercise.png)
+
 - **The worksheet** on the left is the question top to bottom, with an
   answer box wherever one is needed: yes/no, multiple choice, a set
   (`{a, b}`, sets of sets, or pairs like `({a}, {b,d})`), a number, a short
@@ -703,7 +707,10 @@ generated from `openprocess/mining/definitions.py`; after editing a definition,
 Likewise [`docs/references.md`](docs/references.md) — every source OpenProcess's
 notation and algorithms follow, also in the app under **Help ▸ References** —
 is generated from `openprocess/references.py` with
-`python -m openprocess.references > docs/references.md`.
+`python -m openprocess.references > docs/references.md`. The screenshots in
+this README come from the app itself: `python docs/make_screenshots.py`
+renders every page offscreen into `docs/screenshots/`, so run it after a
+change to the app's looks.
 
 The engines (`openprocess.mining`, `openprocess.ml`, `openprocess.sim`, `openprocess.analysis`)
 have **no dependencies**, so they work in a notebook or a script:
@@ -730,6 +737,10 @@ Miner, a fitness check), *Compare discovery* (three miners side by side),
 confidence* (bootstrap intervals, a test and a plot; needs the `science`
 extra) and *Predict the next activity*. Or start empty.
 
+| The canvas: *Compare discovery*, three miners side by side | Summary: every box's key figure, and the process map |
+|---|---|
+| ![The canvas of a Compare discovery analysis, the Compare box's table beside it](docs/screenshots/workflow-canvas.png) | ![The Summary view: a tile per box, the process map under them](docs/screenshots/workflow-summary.png) |
+
 - **The page is the canvas.** Its header has **Canvas | Summary**, then
   **+ Add box**, **Run ▶**, and **⋯** for Re-run, Record, Export experiment
   and Save. The sidebar beside it lists the folder's analyses and, folded
@@ -786,8 +797,18 @@ extra) and *Predict the next activity*. Or start empty.
   `boxes/`, so it is listed under *Yours* and can be used in any workflow.
 - **Export experiment** (under ⋯) writes a zip with the workflow file and its record,
   the inputs, your boxes, every result as a file (CSV, PNML, SVG, XES), a
-  `requirements.lock` and a README that says what was run: supplementary
-  material for a paper, which `openprocess run --check` can verify.
+  `requirements.lock`, a `run.py` that runs the same analysis as a plain
+  script, and a README that says what was run: supplementary material for a
+  paper, which `openprocess run --check` can verify. Drop such a zip on
+  OpenProcess and it is unpacked into a folder of its own and run again.
+- **Export as Python script** (under ⋯) writes the analysis as a `.py` file:
+  the same boxes, settings and connections, run with `python analysis.py`,
+  the results written beside it.
+- **Every result knows where it came from**: a figure saved as SVG carries
+  the analysis, the box, its settings and the result's fingerprint in its
+  metadata; a CSV gets a `.provenance.json` beside it.
+- **⌘Z and ⇧⌘Z** undo and redo on the canvas: boxes, connections, moves,
+  settings, groups.
 - **The side panel** resizes by dragging the gap beside it; double-click the
   gap, or *View ▸ Reset Workflow Layout*, for its default width.
 - **Connections** (at the bottom of the sidebar, or *View ▸ Connections*)

{openprocess-0.10.6 → openprocess-0.11.0}/openprocess/__init__.py

@@ -48,7 +48,7 @@ from .sim.simulator import Simulator
 #: The one place the version number is written (pyproject.toml, the update
 #: check and packaging/build.py read it from here).  A release is tagged
 #: "v" + this, e.g. v0.2.0.
-__version__ = "0.10.6"
+__version__ = "0.11.0"
 
 __all__ = [
     "Arc", "BindingElement", "CPNet", "Marking", "Multiset", "Page", "Place",

{openprocess-0.10.6 → openprocess-0.11.0}/openprocess/flow/boxes/science.py

@@ -110,11 +110,13 @@ def correlate(table: Table) -> Table:
 @box(name="Plot", group="Science", needs="matplotlib")
 def plot(scores: list[Scores] = (), tables: list[Table] = (),
          x: Column = "", y: Column = "") -> Figure:
-    """Bars per model for scores, histograms for bootstrap tables, or a line
-    of column *y* against column *x* of a table (a sweep). The figure is a
+    """Bars per model for scores, histograms for bootstrap tables, or column
+    *y* of a table against column *x*: bars when *x* holds names (a model per
+    bar), a line when it holds numbers (a sweep). Once *x* and *y* are set
+    they decide the figure, whatever else is connected. The figure is a
     matplotlib figure, converted to SVG; its code is this box's code.
 
-    x: a column of the table to put on the x axis (lines only)
+    x: a column of the table to put on the x axis
     y: the column to plot against it
     """
     import matplotlib
@@ -122,7 +124,24 @@ def plot(scores: list[Scores] = (), tables: list[Table] = (),
     import matplotlib.pyplot as plt
     fig, ax = plt.subplots(figsize=(5.5, 3.2))
     scores, tables = list(scores), list(tables)
-    if scores:
+    if tables and x and y:
+        for table in tables:
+            for name in (x, y):
+                if name not in table.columns:
+                    raise ValueError(f"{table.name} has no column {name!r}; it has {', '.join(table.columns)}")
+        numeric = all(isinstance(v, (int, float)) and not isinstance(v, bool) for t in tables for v in t.column(x))
+        for table in tables:
+            values = [float(v) for v in table.column(y)]
+            if numeric:
+                ax.plot(table.column(x), values, marker="o", label=table.name)
+            else:
+                ax.bar([str(v) for v in table.column(x)], values, label=table.name)
+        ax.set_xlabel(x)
+        ax.set_ylabel(y)
+        if len(tables) > 1:
+            ax.legend(fontsize=8)
+        caption = f"{y} against {x}."
+    elif scores:
         metrics = [m for m in dict.fromkeys(k for s in scores for k in s.metrics)
                    if all(isinstance(s.metrics.get(m, 0.0), (int, float)) for s in scores)]
         width = 0.8 / max(1, len(metrics))
@@ -134,14 +153,6 @@ def plot(scores: list[Scores] = (), tables: list[Table] = (),
         ax.set_ylim(0, 1.05)
         ax.legend(fontsize=8)
         caption = f"{len(scores)} models, {len(metrics)} scores each."
-    elif tables and x and y:
-        for table in tables:
-            ax.plot(table.column(x), table.column(y), marker="o", label=table.name)
-        ax.set_xlabel(x)
-        ax.set_ylabel(y)
-        if len(tables) > 1:
-            ax.legend(fontsize=8)
-        caption = f"{y} against {x}."
     elif tables:
         for table in tables:
             if table.samples:
@@ -150,7 +161,7 @@ def plot(scores: list[Scores] = (), tables: list[Table] = (),
         ax.legend(fontsize=8)
         caption = f"{len(tables)} bootstrap distribution{'s' if len(tables) != 1 else ''}."
     else:
-        raise ValueError("Connect scores, or tables with samples or an x and y column")
+        raise ValueError("Connect scores, or tables with samples, or a table and set both x and y")
     fig.tight_layout()
     figure = convert(fig, Figure)
     plt.close(fig)

openprocess-0.11.0/openprocess/flow/history.py

@@ -0,0 +1,113 @@
+"""Undo and redo for a workflow, by snapshots.
+
+A workflow is small (its dict form, :meth:`Workflow.to_dict`, is a few
+kilobytes), so every change keeps the whole state before it: adding,
+removing, wiring, moving or grouping boxes, a setting, a rename.  Undo puts
+a snapshot back; the page then runs the boxes again, and the cache serves
+the ones that did not change.  Snapshots are taken where the page already
+learns of a change, so no edit is instrumented by hand, and a box author
+never sees any of this.
+"""
+
+from __future__ import annotations
+
+import time
+
+#: How many steps back are kept.
+LIMIT = 100
+#: A drag arrives as several moves; those within this many seconds are one step.
+MOVE_SECONDS = 1.5
+
+
+def describe(before: dict, after: dict) -> str:
+    """What changed from ``before`` to ``after``, for "Undo adding a box"."""
+    b = {n["id"]: n for n in before.get("boxes", [])}
+    a = {n["id"]: n for n in after.get("boxes", [])}
+    added, removed = set(a) - set(b), set(b) - set(a)
+    if added:
+        return "adding a box" if len(added) == 1 else f"adding {len(added)} boxes"
+    if removed:
+        return "removing a box" if len(removed) == 1 else f"removing {len(removed)} boxes"
+    if before.get("connections") != after.get("connections"):
+        return "a connection"
+    if before.get("groups") != after.get("groups"):
+        return "grouping"
+    for node_id in a:
+        if a[node_id].get("settings") != b[node_id].get("settings"):
+            return "a setting"
+        if a[node_id].get("title", "") != b[node_id].get("title", ""):
+            return "a rename"
+    if any(a[i].get("position") != b[i].get("position") for i in a):
+        return "a move"
+    if any(a[i].get("layout") != b[i].get("layout") for i in a):
+        return "tidying a drawing"
+    if before.get("name") != after.get("name"):
+        return "a rename"
+    return "a change"
+
+
+class History:
+    """The states a workflow went through; :attr:`state` is the current one."""
+
+    def __init__(self, snapshot: dict, limit: int = LIMIT) -> None:
+        self.state = snapshot
+        self.limit = limit
+        self.undo_stack: list[dict] = []
+        self.redo_stack: list[dict] = []
+        self._last: tuple[str | None, float] = (None, 0.0)
+
+    def record(self, snapshot: dict, kind: str = "change", now: float | None = None) -> bool:
+        """The workflow is now ``snapshot``; the state before it becomes undoable.
+        Returns whether anything changed.  ``kind`` "move" folds a drag's
+        steps into one."""
+        if snapshot == self.state:
+            return False
+        now = time.monotonic() if now is None else now
+        last_kind, last_time = self._last
+        if not (kind == "move" and last_kind == "move" and now - last_time < MOVE_SECONDS and self.undo_stack):
+            self.undo_stack.append(self.state)
+            del self.undo_stack[:-self.limit]
+        self.redo_stack.clear()
+        self.state = snapshot
+        self._last = (kind, now)
+        return True
+
+    @property
+    def can_undo(self) -> bool:
+        return bool(self.undo_stack)
+
+    @property
+    def can_redo(self) -> bool:
+        return bool(self.redo_stack)
+
+    @property
+    def undo_label(self) -> str:
+        return describe(self.undo_stack[-1], self.state) if self.undo_stack else ""
+
+    @property
+    def redo_label(self) -> str:
+        return describe(self.state, self.redo_stack[-1]) if self.redo_stack else ""
+
+    def undo(self) -> tuple[str, dict] | None:
+        """Step back: (what is undone, the state to restore), or None."""
+        if not self.undo_stack:
+            return None
+        before = self.undo_stack.pop()
+        label = describe(before, self.state)
+        self.redo_stack.append(self.state)
+        self.state = before
+        self._last = (None, 0.0)
+        return label, before
+
+    def redo(self) -> tuple[str, dict] | None:
+        if not self.redo_stack:
+            return None
+        after = self.redo_stack.pop()
+        label = describe(self.state, after)
+        self.undo_stack.append(self.state)
+        self.state = after
+        self._last = (None, 0.0)
+        return label, after
+
+
+__all__ = ["History", "describe", "LIMIT", "MOVE_SECONDS"]

openprocess-0.11.0/openprocess/flow/provenance.py

@@ -0,0 +1,110 @@
+"""Where a result came from, carried with it and written into the files it becomes.
+
+The runner stamps every value a box gives with a :class:`Provenance`: the
+analysis, the box and its settings, and the result's key (the fingerprint of
+the box's code, its settings and its inputs, which is also the cache key).
+A figure saved as SVG carries it in a ``<metadata>`` block; a table saved as
+CSV, or a figure as PNG, gets a ``.provenance.json`` beside it.  A figure in
+a paper then points back at the analysis that made it.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import re
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from xml.sax.saxutils import escape
+
+
+@dataclass
+class Provenance:
+    workflow: str
+    box: str
+    title: str
+    settings: dict
+    key: str
+    openprocess: str
+    when: str
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+    def json(self) -> str:
+        return json.dumps(self.as_dict(), indent=2, ensure_ascii=False, default=str)
+
+    def line(self) -> str:
+        return (f"{self.title} ({self.box}) in “{self.workflow}”, OpenProcess {self.openprocess}, "
+                f"{self.when}; key {self.key[:12]}")
+
+    def svg_metadata(self) -> str:
+        """A Dublin Core block for an SVG's ``<metadata>``."""
+        return (
+            '<metadata id="openprocess-provenance">'
+            '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" '
+            'xmlns:dc="http://purl.org/dc/elements/1.1/"><rdf:Description>'
+            f"<dc:creator>OpenProcess {escape(self.openprocess)}</dc:creator>"
+            f"<dc:source>{escape(self.line())}</dc:source>"
+            f"<dc:date>{escape(self.when)}</dc:date>"
+            f"<dc:description>{escape(self.json())}</dc:description>"
+            "</rdf:Description></rdf:RDF></metadata>"
+        )
+
+
+def make(workflow, node, spec, settings: dict, key: str) -> Provenance:
+    from .. import __version__
+    plain = {}
+    for name, value in settings.items():
+        if hasattr(value, "describe"):             # a sweep
+            value = value.describe()
+        plain[name] = str(value) if isinstance(value, Path) else value
+    return Provenance(workflow.name, spec.id, workflow.title(node), plain, key, __version__,
+                      _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"))
+
+
+def stamp(value, provenance: Provenance) -> bool:
+    """Attach ``provenance`` to ``value`` when it can carry one (a dataclass
+    can; a number or a string cannot).  Returns whether it did."""
+    if value is None or isinstance(value, (bool, int, float, str, bytes, list, tuple, dict, set, frozenset)):
+        return False
+    try:
+        object.__setattr__(value, "provenance", provenance)
+    except (AttributeError, TypeError):
+        return False
+    return True
+
+
+def of(value) -> Provenance | None:
+    found = getattr(value, "provenance", None)
+    return found if isinstance(found, Provenance) else None
+
+
+_SVG_OPEN = re.compile(r"<svg\b[^>]*>", re.S)
+
+
+def with_metadata(svg: str, provenance: Provenance | None) -> str:
+    """The SVG text with the provenance in a ``<metadata>`` block after the opening tag."""
+    if provenance is None:
+        return svg
+    match = _SVG_OPEN.search(svg)
+    if match is None:
+        return svg
+    return svg[:match.end()] + "\n" + provenance.svg_metadata() + svg[match.end():]
+
+
+def sidecar_path(path) -> Path:
+    """``table.csv`` → ``table.provenance.json`` beside it."""
+    path = Path(path)
+    return path.with_name(path.stem + ".provenance.json")
+
+
+def write_sidecar(path, provenance: Provenance | None) -> Path | None:
+    if provenance is None:
+        return None
+    target = sidecar_path(path)
+    target.write_text(provenance.json() + "\n", encoding="utf-8")
+    return target
+
+
+__all__ = ["Provenance", "make", "of", "sidecar_path", "stamp", "with_metadata", "write_sidecar"]

{openprocess-0.10.6 → openprocess-0.11.0}/openprocess/flow/record.py

@@ -310,7 +310,9 @@ def export_experiment(workflow: Workflow, run: Run | None, target: str | Path,
     lines = [f"# {name}", "", f"Exported {record.saved} with OpenProcess {record.versions.get('openprocess', '')}, "
              f"Python {record.versions.get('python', '')}.", "",
              "Run it again with `openprocess run " + f"{name}.cpnflow --check`: it fails if any result differs "
-             "from the recorded one. `requirements.lock` is the environment it ran in.", "", "## Boxes", ""]
+             "from the recorded one. `requirements.lock` is the environment it ran in. `run.py` is the same "
+             "analysis as a plain Python script (`python run.py`). Or drop this zip on OpenProcess: it unpacks "
+             "it into a folder and runs it.", "", "## Boxes", ""]
     for node in workflow.order():
         spec = workflow.spec(node)
         settings = ", ".join(f"{k} = {v}" for k, v in node.settings.items()) or "no settings"
@@ -335,6 +337,8 @@ def export_experiment(workflow: Workflow, run: Run | None, target: str | Path,
     with zipfile.ZipFile(target, "w", zipfile.ZIP_DEFLATED) as zipped:
         zipped.writestr(f"{name}.cpnflow", json.dumps(data, indent=2, ensure_ascii=False, default=str))
         zipped.writestr("requirements.lock", requirements_lock(record))
+        from .script import script_text
+        zipped.writestr("run.py", script_text(workflow, "run.py"))
         zipped.writestr("CITATIONS.bib", "\n\n".join(e.bibtex() for e in entries) + "\n")
         zipped.writestr("README.md", "\n".join(lines) + "\n")
         for item in record.inputs:
@@ -368,6 +372,62 @@ def _describe(value) -> str:
     return type(value).__name__ if value is not None else "done"
 
 
+def is_experiment(path) -> bool:
+    """Whether ``path`` is a zip :func:`export_experiment` wrote: one ``.cpnflow`` at the top."""
+    import zipfile
+    try:
+        with zipfile.ZipFile(path) as zipped:
+            return sum(1 for n in zipped.namelist() if n.endswith(".cpnflow") and "/" not in n) == 1
+    except (OSError, zipfile.BadZipFile):
+        return False
+
+
+def import_experiment(archive, into) -> Path:
+    """Unpack an exported experiment into a new folder under ``into`` (named
+    after the zip) and give back its workflow file, ready to open: the file
+    settings point at ``inputs/``, the folder's ``boxes/`` holds the custom
+    boxes (a box is found by its function name there), and the recorded
+    results are kept for the reproducibility check."""
+    import zipfile
+    archive = Path(archive)
+    with zipfile.ZipFile(archive) as zipped:
+        names = zipped.namelist()
+        flows = [n for n in names if n.endswith(".cpnflow") and "/" not in n]
+        if len(flows) != 1:
+            raise ValueError(f"{archive.name} is not an exported experiment (one .cpnflow at the top is needed)")
+        folder = Path(into) / archive.stem
+        counter = 2
+        while folder.exists():
+            folder = Path(into) / f"{archive.stem} {counter}"
+            counter += 1
+        folder.mkdir(parents=True)
+        for name in names:
+            parts = Path(name).parts
+            if name.endswith("/") or not parts or ".." in parts or Path(name).is_absolute():
+                continue
+            target = folder / name
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(zipped.read(name))
+    flow_file = folder / flows[0]
+    data = json.loads(flow_file.read_text(encoding="utf-8"))
+    moved: dict[tuple[str, str], str] = {}
+    for item in data.get("record", {}).get("inputs", []):
+        new = f"inputs/{Path(item['file']).name}"
+        if (folder / new).is_file():
+            moved[(item["node"], item["setting"])] = new
+            item["file"] = new
+    for item in data.get("record", {}).get("custom_boxes", []):
+        new = f"boxes/{Path(item['file']).name}"
+        if (folder / new).is_file():
+            item["file"] = new
+    for box in data.get("boxes", []):
+        for setting in list(box.get("settings", {})):
+            if (box["id"], setting) in moved:
+                box["settings"][setting] = moved[(box["id"], setting)]
+    flow_file.write_text(json.dumps(data, indent=2, ensure_ascii=False, default=str), encoding="utf-8")
+    return flow_file
+
+
 def _as_file(value, stem: str):
     """(name, bytes or text) for a result worth a file of its own."""
     if isinstance(value, Table):
@@ -396,5 +456,9 @@ def _as_file(value, stem: str):
     return None
 
 
-__all__ = ["FORMAT", "Record", "check", "differences", "environment", "export_experiment", "fingerprint",
-           "load", "make_record", "requirements_lock", "save", "sha256_file", "sha256_text", "versions"]
+#: (name, bytes or text) for a result worth a file of its own; the script an experiment carries uses it.
+as_file = _as_file
+
+__all__ = ["FORMAT", "Record", "as_file", "check", "differences", "environment", "export_experiment",
+           "fingerprint", "import_experiment", "is_experiment", "load", "make_record", "requirements_lock",
+           "save", "sha256_file", "sha256_text", "versions"]

{openprocess-0.10.6 → openprocess-0.11.0}/openprocess/flow/runner.py

@@ -317,6 +317,7 @@ class Runner:
             result.values, result.explanation = cached
             result.value = result.values.get("out", next(iter(result.values.values()), None))
             result.status, result.cached = DONE, True
+            self._stamp(result, workflow, node, spec, settings)
             return result
         # Run it
         result.status = RUNNING
@@ -341,8 +342,17 @@ class Runner:
         result.values, result.value, result.explanation = values, values.get("out", value), explanation
         result.status = DONE
         self.cache.put(result.key, values, explanation)
+        self._stamp(result, workflow, node, spec, settings)
         return result
 
+    @staticmethod
+    def _stamp(result: Result, workflow: Workflow, node: Node, spec: BoxSpec, settings: dict) -> None:
+        """Every value a box gives carries where it came from (:mod:`openprocess.flow.provenance`)."""
+        from .provenance import make, stamp
+        info = make(workflow, node, spec, settings, result.key)
+        for out in result.values.values():
+            stamp(out, info)
+
     @staticmethod
     def _outputs(spec: BoxSpec, value) -> dict[str, Any]:
         if spec.result_type is not None: