feat: Add configurable datafile template (#1269)

tpoliaw · web-flow · commit bea726d56d7a · 2025-11-06T16:46:33.000Z
Detector file name defaults  to `{instrument}-{scan_id}-{device_name}`
when using the numtracker backed path provider but can now be configured
by setting `detector_file_template` in the `numtracker` section of the
config.
diff --git a/helm/blueapi/config_schema.json b/helm/blueapi/config_schema.json
@@ -173,6 +173,11 @@
                     "minLength": 1,
                     "title": "Url",
                     "type": "string"
+                },
+                "detector_file_template": {
+                    "default": "{instrument}-{scan_id}-{device_name}",
+                    "title": "Detector File Template",
+                    "type": "string"
                 }
             },
             "title": "NumtrackerConfig",
diff --git a/helm/blueapi/values.schema.json b/helm/blueapi/values.schema.json
@@ -654,6 +654,11 @@
                     "title": "NumtrackerConfig",
                     "type": "object",
                     "properties": {
+                        "detector_file_template": {
+                            "title": "Detector File Template",
+                            "default": "{instrument}-{scan_id}-{device_name}",
+                            "type": "string"
+                        },
                         "url": {
                             "title": "Url",
                             "default": "http://localhost:8406/graphql",
diff --git a/src/blueapi/config.py b/src/blueapi/config.py
@@ -221,6 +221,7 @@ def id_token_signing_alg_values_supported(self) -> list[str]:
 
 class NumtrackerConfig(BlueapiBaseModel):
     url: HttpUrl = HttpUrl("http://localhost:8406/graphql")
+    detector_file_template: str = "{instrument}-{scan_id}-{device_name}"
 
 
 class ApplicationConfig(BlueapiBaseModel):
diff --git a/src/blueapi/core/context.py b/src/blueapi/core/context.py
@@ -109,35 +109,37 @@ def __post_init__(self, configuration: ApplicationConfig | None):
         if not configuration:
             return
 
-        if configuration.numtracker is not None:
+        if (nt_conf := configuration.numtracker) is not None:
             if configuration.env.metadata is not None:
-                self.numtracker = NumtrackerClient(url=configuration.numtracker.url)
+                self.numtracker = NumtrackerClient(url=nt_conf.url)
             else:
                 raise InvalidConfigError(
                     "Numtracker url has been configured, but there is no instrument or"
                     " instrument_session in the environment metadata"
                 )
 
-        if self.numtracker is not None:
-            numtracker = self.numtracker
-
             path_provider = StartDocumentPathProvider()
             set_path_provider(path_provider)
+
             self.run_engine.subscribe(path_provider.run_start, "start")
             self.run_engine.subscribe(path_provider.run_stop, "stop")
 
+            # local reference so it's available in _update_scan_num
+            numtracker = self.numtracker
+
             def _update_scan_num(md: dict[str, Any]) -> int:
                 scan = numtracker.create_scan(
                     md["instrument_session"], md["instrument"]
                 )
                 md["data_session_directory"] = str(scan.scan.directory.path)
+                md["detector_file_template"] = nt_conf.detector_file_template
                 md["scan_file"] = scan.scan.scan_file
                 return scan.scan.scan_number
 
             self.run_engine.scan_id_source = _update_scan_num
 
         self.with_config(configuration.env)
-        if self.numtracker and not isinstance(
+        if configuration.numtracker and not isinstance(
             get_path_provider(), StartDocumentPathProvider
         ):
             raise InvalidConfigError(
diff --git a/src/blueapi/utils/path_provider.py b/src/blueapi/utils/path_provider.py
@@ -3,16 +3,13 @@
 from event_model import RunStart, RunStop
 from ophyd_async.core import PathInfo, PathProvider
 
-DEFAULT_TEMPLATE = "{instrument}-{scan_id}-{device_name}"
-
 
 class StartDocumentPathProvider(PathProvider):
     """A PathProvider that sources from metadata in a RunStart document.
 
-    This uses metadata from a RunStart document to determine file names and data session
-    directories. The file naming defaults to "{instrument}-{scan_id}-{device_name}}", so
-    the file name is incremented by scan number. A template can be included in the
-    StartDocument to allow for custom naming conventions.
+    This uses metadata from a RunStart document to determine file names and
+    data session directories. A template can be included in the StartDocument
+    to allow for custom naming conventions.
 
     """
 
@@ -38,7 +35,7 @@ def __call__(self, device_name: str | None = None) -> PathInfo:
 
         The default template for file naming is: "{instrument}-{scan_id}-{device_name}"
         however, this can be changed by providing a template in the start document. For
-        example: "template": "custom-{device_name}-{scan_id}".
+        example: "detector_file_template": "custom-{device_name}-{scan_id}".
 
         If you do not provide a data_session_directory it will default to "/tmp".
         """
@@ -47,7 +44,9 @@ def __call__(self, device_name: str | None = None) -> PathInfo:
                 "Start document not found. This call must be made inside a run."
             )
         else:
-            template = self._docs[-1].get("data_file_path_template", DEFAULT_TEMPLATE)
+            template = self._docs[-1].get("detector_file_template")
+            if not template:
+                raise ValueError("detector_file_template must be set in metadata")
             sub_path = template.format_map(
                 self._docs[-1] | {"device_name": device_name}
             )
diff --git a/tests/unit_tests/utils/test_path_provider.py b/tests/unit_tests/utils/test_path_provider.py
@@ -18,6 +18,7 @@ def start_doc_default_template() -> dict:
         "versions": {"ophyd": "1.10.0", "bluesky": "1.13"},
         "data_session": "ab123",
         "instrument": "p01",
+        "detector_file_template": "{instrument}-{scan_id}-{device_name}",
         "data_session_directory": "/p01/ab123",
         "scan_id": 22,
         "plan_type": "generator",
@@ -61,7 +62,7 @@ def start_doc_custom_template() -> dict:
         "instrument": "p01",
         "data_session_directory": "/p01/ab123",
         "scan_id": 22,
-        "data_file_path_template": "{instrument}-{scan_id}-{device_name}-custom",
+        "detector_file_template": "{instrument}-{scan_id}-{device_name}-custom",
         "plan_type": "generator",
         "plan_name": "count",
         "detectors": ["det"],
@@ -99,6 +100,7 @@ def start_doc_missing_instrument() -> dict:
         "uid": "27c48d2f-d8c6-4ac0-8146-fedf467ce11f",
         "time": 1741264729.96875,
         "versions": {"ophyd": "1.10.0", "bluesky": "1.13"},
+        "detector_file_template": "{instrument}-{scan_id}-{device_name}",
         "data_session": "ab123",
         "data_session_directory": "/p01/ab123",
         "scan_id": 22,
@@ -137,6 +139,7 @@ def start_doc_missing_scan_id() -> dict:
         "versions": {"ophyd": "1.10.0", "bluesky": "1.13"},
         "data_session": "ab123",
         "instrument": "p01",
+        "detector_file_template": "{instrument}-{scan_id}-{device_name}",
         "data_session_directory": "/p01/ab123",
         "plan_type": "generator",
         "plan_name": "count",
@@ -171,6 +174,7 @@ def start_doc_default_data_session_directory() -> dict:
         "uid": "27c48d2f-d8c6-4ac0-8146-fedf467ce11f",
         "time": 1741264729.96875,
         "versions": {"ophyd": "1.10.0", "bluesky": "1.13"},
+        "detector_file_template": "{instrument}-{scan_id}-{device_name}",
         "data_session": "ab123",
         "instrument": "p01",
         "scan_id": 22,
@@ -240,6 +244,7 @@ def start_doc_1() -> dict:
         "versions": {"ophyd": "1.10.0", "bluesky": "1.13"},
         "data_session": "ab123",
         "instrument": "p01",
+        "detector_file_template": "{instrument}-{scan_id}-{device_name}",
         "data_session_directory": "/p01/ab123",
         "scan_id": 50,
         "plan_type": "generator",
@@ -279,6 +284,7 @@ def start_doc_2() -> dict:
         "versions": {"ophyd": "1.10.0", "bluesky": "1.13"},
         "data_session": "ab123",
         "instrument": "p02",
+        "detector_file_template": "{instrument}-{scan_id}-{device_name}",
         "data_session_directory": "/p02/ab123",
         "scan_id": 51,
         "plan_type": "generator",
@@ -378,3 +384,11 @@ def test_start_document_path_provider_run_stop_called_out_of_order_raises(
         "This is not supported. If you need to do this speak to core DAQ.",
     ):
         pp.run_stop(name="stop", stop_document=stop_doc_1)
+
+
+def test_error_if_template_missing(start_doc_1: RunStart):
+    pp = StartDocumentPathProvider()
+    start_doc_1.pop("detector_file_template")
+    pp.run_start("start", start_doc_1)
+    with pytest.raises(ValueError, match="detector_file_template"):
+        pp("foo")
