fix: Make the path provider stack start docs (#1251)

Makes the `StartDocumentPathProvider` stack docs, using the latest for
path determination.

Author: abbiemery

src/blueapi/utils/path_provider.py

@@ -17,19 +17,21 @@ class StartDocumentPathProvider(PathProvider):
     """
 
     def __init__(self) -> None:
-        self._doc: RunStart | None = None
+        self._docs: list[RunStart] = []
 
     def run_start(self, name: str, start_document: RunStart) -> None:
-        if name == "start" and self._doc is None:
-            self._doc = start_document
+        if name == "start":
+            self._docs.append(start_document)
 
     def run_stop(self, name: str, stop_document: RunStop) -> None:
-        if (
-            name == "stop"
-            and self._doc is not None
-            and stop_document.get("run_start") == self._doc["uid"]
-        ):
-            self._doc = None
+        if name == "stop":
+            if stop_document.get("run_start") == self._docs[-1]["uid"]:
+                self._docs.pop()
+            else:
+                raise BlueskyRunStructureError(
+                    "Close run called, but not for the inner most run. "
+                    "This is not supported. If you need to do this speak to core DAQ."
+                )
 
     def __call__(self, device_name: str | None = None) -> PathInfo:
         """Returns the directory path and filename for a given data_session.
@@ -40,14 +42,21 @@ def __call__(self, device_name: str | None = None) -> PathInfo:
 
         If you do not provide a data_session_directory it will default to "/tmp".
         """
-        if self._doc is None:
-            raise AttributeError(
+        if not self._docs:
+            raise BlueskyRunStructureError(
                 "Start document not found. This call must be made inside a run."
             )
         else:
-            template = self._doc.get("data_file_path_template", DEFAULT_TEMPLATE)
-            sub_path = template.format_map(self._doc | {"device_name": device_name})
+            template = self._docs[-1].get("data_file_path_template", DEFAULT_TEMPLATE)
+            sub_path = template.format_map(
+                self._docs[-1] | {"device_name": device_name}
+            )
             data_session_directory = Path(
-                self._doc.get("data_session_directory", "/tmp")
+                self._docs[-1].get("data_session_directory", "/tmp")
             )
             return PathInfo(directory_path=data_session_directory, filename=sub_path)
+
+
+class BlueskyRunStructureError(Exception):
+    def __init__(self, message):
+        super().__init__(message)

tests/unit_tests/utils/test_path_provider.py

@@ -4,7 +4,10 @@
 from event_model import RunStart, RunStop
 from ophyd_async.core import PathInfo
 
-from blueapi.utils.path_provider import StartDocumentPathProvider
+from blueapi.utils.path_provider import (
+    BlueskyRunStructureError,
+    StartDocumentPathProvider,
+)
 
 
 @pytest.fixture
@@ -217,7 +220,7 @@ def test_start_document_path_provider_run_start_called_with_different_document_s
     pp = StartDocumentPathProvider()
     pp.run_start(name="stop", start_document=stop_doc_default_template)  # type: ignore
 
-    assert pp._doc is None
+    assert pp._docs == []
 
 
 def test_start_document_path_provider_run_stop_called_with_different_document_skips(
@@ -226,18 +229,18 @@ def test_start_document_path_provider_run_stop_called_with_different_document_sk
     pp = StartDocumentPathProvider()
     pp.run_stop(name="start", stop_document=start_doc_default_template)  # type: ignore
 
-    assert pp._doc is None
+    assert pp._docs == []
 
 
 @pytest.fixture
-def start_doc() -> dict:
+def start_doc_1() -> dict:
     return {
         "uid": "fa2feced-4098-4c0e-869d-285d2a69c24a",
         "time": 1690463918.3893268,
         "versions": {"ophyd": "1.10.0", "bluesky": "1.13"},
         "data_session": "ab123",
-        "instrument": "p02",
-        "data_session_directory": "/p02/ab123",
+        "instrument": "p01",
+        "data_session_directory": "/p01/ab123",
         "scan_id": 50,
         "plan_type": "generator",
         "plan_name": "count",
@@ -257,7 +260,7 @@ def start_doc() -> dict:
 
 
 @pytest.fixture
-def stop_doc() -> dict:
+def stop_doc_1() -> dict:
     return {
         "run_start": "fa2feced-4098-4c0e-869d-285d2a69c24a",
         "time": 1690463920.3893268,
@@ -268,68 +271,110 @@ def stop_doc() -> dict:
     }
 
 
-def test_start_document_path_provider_start_doc_persists_until_stop_with_matching_id(
-    start_doc: RunStart,
-    stop_doc: RunStop,
-    start_doc_default_template: RunStart,
-    stop_doc_default_template: RunStop,
-):
-    pp = StartDocumentPathProvider()
-    pp.run_start(name="start", start_document=start_doc)
-
-    assert pp._doc == start_doc
-    assert pp._doc["uid"] == "fa2feced-4098-4c0e-869d-285d2a69c24a"  # type: ignore
-
-    pp.run_start(name="start", start_document=start_doc_default_template)
-    assert pp._doc == start_doc
-    assert pp._doc["uid"] == "fa2feced-4098-4c0e-869d-285d2a69c24a"  # type: ignore
+@pytest.fixture
+def start_doc_2() -> dict:
+    return {
+        "uid": "27c48d2f-d8c6-4ac0-8146-fedf467ce11f",
+        "time": 1690463918.3893268,
+        "versions": {"ophyd": "1.10.0", "bluesky": "1.13"},
+        "data_session": "ab123",
+        "instrument": "p02",
+        "data_session_directory": "/p02/ab123",
+        "scan_id": 51,
+        "plan_type": "generator",
+        "plan_name": "count",
+        "detectors": ["det"],
+        "num_points": 1,
+        "num_intervals": 0,
+        "plan_args": {
+            "detectors": [
+                "<ophyd_async.epics.adaravis._aravis.AravisDetector object at 0x7f74c02b8710>"  # NOQA: E501
+            ],
+            "num": 1,
+            "delay": 0.0,
+        },
+        "hints": {"dimensions": [[["time"], "primary"]]},
+        "shape": [1],
+    }
 
-    pp.run_stop(name="stop", stop_document=stop_doc_default_template)
-    assert pp._doc == start_doc
-    assert pp._doc["uid"] == "fa2feced-4098-4c0e-869d-285d2a69c24a"  # type: ignore
 
-    pp.run_stop(name="stop", stop_document=stop_doc)
-    assert pp._doc is None
+@pytest.fixture
+def stop_doc_2() -> dict:
+    return {
+        "run_start": "27c48d2f-d8c6-4ac0-8146-fedf467ce11f",
+        "time": 1690463920.3893268,
+        "uid": "401ad197-5456-4a7d-ba5b-9cf8ad38d914",
+        "exit_status": "success",
+        "reason": "",
+        "num_events": {"primary": 1},
+    }
 
 
-def test_start_document_path_provider_nested_runs_use_parent_run_info(
-    start_doc_default_template: RunStart,
-    stop_doc_default_template: RunStop,
-    start_doc: RunStart,
-    stop_doc: RunStop,
+def test_start_document_path_provider_nested_runs_use_info_from_last_start_doc(
+    start_doc_1: RunStart,
+    stop_doc_1: RunStop,
+    start_doc_2: RunStart,
+    stop_doc_2: RunStop,
 ):
     pp = StartDocumentPathProvider()
-    pp.run_start(name="start", start_document=start_doc_default_template)
-    parent_path_info = pp("det")
 
-    assert pp._doc == start_doc_default_template
-    assert pp._doc["uid"] == "27c48d2f-d8c6-4ac0-8146-fedf467ce11f"  # type: ignore
-    assert parent_path_info == PathInfo(
+    pp.run_start(name="start", start_document=start_doc_1)
+    start_doc_1_path_info = PathInfo(
         directory_path=PosixPath("/p01/ab123"),
-        filename="det-p01-22",
+        filename="det-p01-50",
         create_dir_depth=0,
     )
 
-    pp.run_start(name="start", start_document=start_doc)
-    assert pp._doc == start_doc_default_template
-    assert pp._doc["uid"] == "27c48d2f-d8c6-4ac0-8146-fedf467ce11f"  # type: ignore
+    assert pp._docs[-1] == start_doc_1
+    assert pp._docs[-1]["uid"] == "fa2feced-4098-4c0e-869d-285d2a69c24a"
+    assert pp("det") == start_doc_1_path_info
+
+    pp.run_start(name="start", start_document=start_doc_2)
+    start_doc_2_path_info = PathInfo(
+        directory_path=PosixPath("/p02/ab123"),
+        filename="det-p02-51",
+        create_dir_depth=0,
+    )
+
+    assert pp._docs[-1] == start_doc_2
+    assert pp._docs[-1]["uid"] == "27c48d2f-d8c6-4ac0-8146-fedf467ce11f"
+    assert pp("det") == start_doc_2_path_info
+
+    assert pp._docs[-2] == start_doc_1
+    assert pp._docs[-2]["uid"] == "fa2feced-4098-4c0e-869d-285d2a69c24a"
 
-    assert pp("det") == parent_path_info
+    pp.run_stop(name="stop", stop_document=stop_doc_2)
 
-    pp.run_stop(name="stop", stop_document=stop_doc)
-    assert pp._doc == start_doc_default_template
-    assert pp._doc["uid"] == "27c48d2f-d8c6-4ac0-8146-fedf467ce11f"  # type: ignore
+    assert pp._docs[-1] == start_doc_1
+    assert pp._docs[-1]["uid"] == "fa2feced-4098-4c0e-869d-285d2a69c24a"
 
-    assert pp("det") == parent_path_info
+    assert pp("det") == start_doc_1_path_info
 
-    pp.run_stop(name="stop", stop_document=stop_doc_default_template)
-    assert pp._doc is None
+    pp.run_stop(name="stop", stop_document=stop_doc_1)
+    assert pp._docs == []
 
 
 def test_start_document_path_provider_called_without_start_raises():
     pp = StartDocumentPathProvider()
     with pytest.raises(
-        AttributeError,
+        BlueskyRunStructureError,
         match="Start document not found. This call must be made inside a run.",
     ):
         pp("det")
+
+
+def test_start_document_path_provider_run_stop_called_out_of_order_raises(
+    start_doc_1: RunStart,
+    stop_doc_1: RunStop,
+    start_doc_2: RunStart,
+):
+    pp = StartDocumentPathProvider()
+    pp.run_start(name="start", start_document=start_doc_1)
+    pp.run_start(name="start", start_document=start_doc_2)
+
+    with pytest.raises(
+        BlueskyRunStructureError,
+        match="Close run called, but not for the inner most run. "
+        "This is not supported. If you need to do this speak to core DAQ.",
+    ):
+        pp.run_stop(name="stop", stop_document=stop_doc_1)