dynamic-systems-testing-framework 1.0.1__py3-none-any.whl

dstf/__init__.py

@@ -0,0 +1,41 @@
+"""Dynamic Systems Testing Framework — regression & unit testing."""
+
+from typing import TYPE_CHECKING
+
+# The DISTRIBUTION name, which is not the import name: you `import dstf`,
+# but you install `dynamic-systems-testing-framework`. They differ because
+# the short name was already taken on PyPI by an unrelated project. Every
+# importlib.metadata lookup must use this constant — a stale literal does not
+# raise, it silently yields the unknown-version fallback below, so
+# tests/test_distribution_name.py pins this to pyproject.toml's [project] name.
+_DIST_NAME = "dynamic-systems-testing-framework"
+
+# Version source-of-truth lives in pyproject.toml; importlib.metadata
+# reads the installed package's metadata so `dstf --version` and any
+# downstream tooling stay in sync without manual duplication.
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version(_DIST_NAME)
+except Exception:  # noqa: BLE001 — fall back during editable / unbuilt installs
+    __version__ = "0.0.0+unknown"
+
+if TYPE_CHECKING:
+    from .plugins import load_plugins
+
+__all__ = ["__version__", "load_plugins"]
+
+
+def __getattr__(name: str):
+    """Lazily expose :func:`dstf.plugins.load_plugins` at package level.
+
+    `import dstf` must stay near-free — the CLI imports it before argparse
+    has even run. Module-level `from .plugins import load_plugins` would
+    drag in the plug-in machinery on every import, so it resolves on first
+    attribute access instead (PEP 562).
+    """
+    if name == "load_plugins":
+        from .plugins import load_plugins
+
+        return load_plugins
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

dstf/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for `python -m dstf`.
+
+Delegates to the same `main_entry` used by the `dstf` console
+script so both invocation forms share one code path.
+"""
+
+from .cli import main_entry
+
+if __name__ == "__main__":
+    main_entry()

dstf/authoring/__init__.py

@@ -0,0 +1,13 @@
+"""The authoring tier's core — the Session, its spec document and the
+capability contract (two-tier design, §4.5–4.6). Pure Python: no UI
+framework is imported here; sub-project 4's shell sits on top.
+
+Importing the package registers the capabilities it ships (the shell then
+lists whatever is registered); the capability modules reach NiceGUI only
+inside their ``panel``, so this import works without the ``[author]``
+extra.
+"""
+
+from .builtin import register_builtins
+
+register_builtins()

dstf/authoring/builtin/__init__.py

@@ -0,0 +1,32 @@
+"""The capabilities that ship with the tool. They register through the same
+call a plug-in makes; the shell learns of them the same way."""
+
+from __future__ import annotations
+
+from ..capabilities import register_capability, registered_capabilities
+
+
+def register_builtins() -> None:
+    """Idempotent, like ``comparison.builtins.register_builtins``."""
+    names = {c.name for c in registered_capabilities()}
+    from .accept import Accept
+    from .edit_criteria import EditCriteria
+    from .edit_family import EditFamily
+    from .edit_on_plot import EditOnPlot
+    from .edit_tree import EditTree
+    from .enqueue import EnqueueTests
+
+    # Before Edit criteria: a folded row's editor reads which elements,
+    # then what the criterion is (a host stacks its panels in this order).
+    if EditFamily.name not in names:
+        register_capability(EditFamily())
+    if EditCriteria.name not in names:
+        register_capability(EditCriteria())
+    if EditTree.name not in names:
+        register_capability(EditTree())
+    if Accept.name not in names:
+        register_capability(Accept())
+    if EnqueueTests.name not in names:
+        register_capability(EnqueueTests())
+    if EditOnPlot.name not in names:
+        register_capability(EditOnPlot())

dstf/authoring/builtin/accept.py

@@ -0,0 +1,205 @@
+"""Accept (§4.6 table, §4.7): SUITE and TEST placements. The selected tests'
+current results become baselines through
+``storage.accept.accept_run_results`` — the one function the CLI's two
+``--accept`` paths call — so the tool cannot accept a result the CLI would
+refuse.
+
+The confirm list says, per selected model, what accepting will do with it,
+including the aborted-run refusal and the comparison's own (a base tolerance
+that is no number, in the comparison's sentence), so it never promises what the shared
+function declines — with one exception it cannot see from here: a trajectory
+carrying NaN/Inf is refused by ``store_reference`` as it writes, and shows up
+in the write's own line instead. The button's own availability is read off
+those same rows, so an enabled Accept always has at least one baseline to
+write. The write reports one line (§4.6 amendment 1): what it stored, every
+refusal with its reason, and the shared function's warning for a baseline
+file that is large (D153).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ...backends.pool import ItemState
+from ...reporting.status import classify, refusal
+from ...storage.accept import accept_run_results
+from ...storage.batch_manifest import unfinished_run_models
+from ..capabilities import Emphasis, Panel, Placement, StoreWrite, plural
+from ..situation import Situation
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from ...storage.reference_store import ReferenceStore
+    from ..session import SessionView
+
+# NO module-level `nicegui` import: `import dstf.authoring` runs
+# register_builtins(), and the Session must import without the extra.
+
+#: The confirm row's verdict on a model — every word but the last is a
+#: reason the shared accept function stores no baseline for it; the last is
+#: what it stores. ``WILL_STORE`` is the one truth the button's count, its
+#: availability and this forecast share.
+REFUSED = "re-run before accepting"
+#: A run that did not finish left a partial result (D151): it is shown on
+#: the test's page, and is no baseline.
+PARTIAL = "a partial result is never a baseline: queue it again"
+NO_RESULT = "no simulation result"
+SIM_FAILED = "simulation failed"
+SIMULATE_ONLY = "simulate-only: no baseline"
+NO_VARIABLES = "no tracked variables in result"
+WILL_STORE = "will store"
+
+#: The states of a test the simulation queue holds.
+_HELD = (ItemState.WAITING, ItemState.RUNNING)
+
+
+def _rows(s: SessionView) -> list[tuple[str, str, str]]:
+    """``(model_id, status, what accept will do)`` for every selected model,
+    in project order."""
+    project = s.project
+    if project is None:
+        return []
+    selection = s.selection.tests
+    work_dir = project.config.work_dir
+    assert work_dir is not None  # resolved in Config.__post_init__
+    unfinished = unfinished_run_models(work_dir)
+    rows: list[tuple[str, str, str]] = []
+    for test in project.tests:
+        model_id = test.model_id
+        if model_id not in selection:
+            continue
+        comp = s.comparisons.get(model_id)
+        status = classify(comp) if comp is not None else ""
+        result = project.results.get(model_id)
+        if s.partial(model_id) is not None:
+            action = PARTIAL  # what its page draws is not a result
+        elif model_id in unfinished:
+            action = REFUSED  # the guard runs before the result is looked at
+        elif result is None:
+            action = NO_RESULT
+        elif not result.success:
+            action = SIM_FAILED
+        elif comp is not None and (refused := refusal(comp)) is not None:
+            # A test the comparison refused: the row says the comparison's
+            # own sentence, which `accept_run_results` skips it with.
+            action = refused
+        elif test.is_simulate_only:
+            # `accept_results` neither stores nor skips these, by design.
+            action = SIMULATE_ONLY
+        elif not result.variables:
+            # `store_reference` returns False for a variable-less result and
+            # `accept_results` skips it with exactly this reason.
+            action = NO_VARIABLES
+        else:
+            action = WILL_STORE
+        rows.append((model_id, status, action))
+    return rows
+
+
+def _report(
+    stored: int,
+    skipped: list[tuple[str, str]],
+    warnings: list[str],
+    notes: list[str],
+    *,
+    reference_dir: Path,
+) -> str:
+    """The one line the queue panel shows. A partial accept has no other way
+    to say which tests it refused and why — or that a baseline file it
+    wrote is large, or which tests it passed over as simulate-only, in the
+    sentences the CLI prints."""
+    parts = [f"Accept: stored {stored} baseline(s) to {reference_dir}"]
+    parts += [f"; skipped {model_id}: {reason}" for model_id, reason in skipped]
+    parts += [f"; {line}" for line in notes]
+    parts += [f"; {line}" for line in warnings]
+    return "".join(parts)
+
+
+class Accept:
+    """The selection's current results as baselines, comparison settings
+    travelling with them as the CLI's accept does."""
+
+    name = "accept"
+    label = "Accept"
+    placements = frozenset({Placement.SUITE, Placement.TEST})
+    #: drawn as this icon where a bar draws icons (the Suite toolbar)
+    icon = "done_all"
+    #: the Test page's strip: the next action for a result that differs
+    #: from its baseline or has none; nothing new to accept otherwise
+    emphasis = {
+        Situation.FAIL: Emphasis.NEXT,
+        Situation.NO_REF: Emphasis.NEXT,
+        Situation.PASS: Emphasis.MENU,
+        Situation.EDITS: Emphasis.MENU,
+        # a criterion's variable to record first: accepted now, the
+        # baseline would not hold it
+        Situation.EDITS_NEW: Emphasis.MENU,
+        Situation.NEW_VARIABLES: Emphasis.MENU,
+        Situation.SIM_FAIL: Emphasis.MENU,
+        Situation.NO_RESULT: Emphasis.MENU,
+        Situation.QUEUED: Emphasis.MENU,
+        Situation.RUNNING: Emphasis.MENU,
+        Situation.CANCELLED: Emphasis.MENU,
+        Situation.START_FAILED: Emphasis.MENU,
+    }
+
+    def available(self, s: SessionView) -> bool | str:
+        project = s.project
+        if project is None:
+            return "no project open"
+        if not s.selection.tests:
+            return "Accept needs a selection"
+        selection = s.selection.tests
+        for test in project.tests:
+            # The Session's refusal (`apply`), said before the click: the
+            # result in memory is about to be replaced by its run's.
+            state = s.queue_state(test.model_id)
+            if test.model_id in selection and state in _HELD:
+                doing = "running" if state is ItemState.RUNNING else "queued"
+                return f"{test.model_id} is {doing}: accept it when its run has ended"
+        # The button's answer comes from the rows the panel draws, so an
+        # enabled button never reads `Accept 0`: a pending, simulate-only or
+        # variable-less result is a row the write will not store, and the
+        # button carries that row's reason.
+        rows = _rows(s)
+        if any(action == WILL_STORE for _, _, action in rows):
+            return True
+        if not rows:
+            return "no successful result in the selection"
+        return rows[0][2]
+
+    def caption(self, s: SessionView) -> str:
+        count = sum(1 for _, _, action in _rows(s) if action == WILL_STORE)
+        return f"Accept {plural(count, 'result')} as baselines"
+
+    def panel(self, s: SessionView, ui_panel: Panel) -> None:
+        from nicegui import ui
+
+        rows = _rows(s)
+        for model_id, status, action in rows:
+            ui.label(f"{model_id} · {status} · {action}").classes("text-xs")
+        ui.button(self.caption(s), on_click=lambda: ui_panel.submit()).props(
+            "dense no-caps"
+        ).mark("accept-submit")
+
+    def act(self, s: SessionView, **inputs: Any) -> StoreWrite:
+        project = s.project
+        if project is None:
+            raise ValueError("no project open")
+        selection = set(s.selection.tests)
+        # Everything the write needs is read HERE: `run` is handed a store
+        # by the Session and holds no view.
+        tests = [t for t in project.tests if t.model_id in selection]
+        results = dict(project.results)
+        work_dir = project.config.work_dir
+        assert work_dir is not None  # resolved in Config.__post_init__
+        reference_dir = project.config.reference_dir
+
+        def run(store: ReferenceStore) -> str:
+            return _report(
+                *accept_run_results(store, tests, results, work_dir),
+                reference_dir=reference_dir,
+            )
+
+        return StoreWrite(models=frozenset(selection), run=run)