Changed doc examples, made run_start NotRequired in resource/stream_r…

…esource
bluesky · Oct 11, 2023 · 7025512 · 7025512
1 parent a389141
commit 7025512
Show file tree

Hide file tree

Showing 3 changed files with 24 additions and 46 deletions.
diff --git a/docs/user/explanations/data-model.rst b/docs/user/explanations/data-model.rst
@@ -477,31 +477,17 @@ See :doc:`external` for details on the role Stream Resource documents play in
 referencing external assets that are natively ragged, such as single-photon detectors,
 or assets where there are many relatively small data sets (e.g. scanned fluorescence data).
 
-Minimal nontrivial valid example:
-
-.. code-block:: python
-
-   # 'Stream Resource' document
-   {'path_semantics': 'posix',
-    'resource_kwargs': {},
-    'resource_path': '/local/path/subdirectory/data_file',
-    'root': '/local/path/',
-    'run_start': '10bf6945-4afd-43ca-af36-6ad8f3540bcd',
-    'spec': 'SOME_SPEC',
-    'stream_names': ['point_det'],
-    'uid': '272132cf-564f-428f-bf6b-149ee4287024'}
-
 Typical example:
 
 .. code-block:: python
 
-   # resource
-   {'spec': 'AD_HDF5',
+   # 'Stream Resource' document
+   {'data_key': 'detector_1',
+    'spec': 'AD_HDF5',
     'root': '/GPFS/DATA/Andor/',
     'resource_path': '2020/01/03/8ff08ff9-a2bf-48c3-8ff3-dcac0f309d7d.h5',
     'resource_kwargs': {'frame_per_point': 1},
     'path_semantics': 'posix',
-    'stream_names': ['point_det'],
     'uid': '3b300e6f-b431-4750-a635-5630d15c81a8',
     'run_start': '10bf6945-4afd-43ca-af36-6ad8f3540bcd'}
 
@@ -518,30 +504,17 @@ See :doc:`external` for details on the role Stream Datum documents play in refer
 external assets that are natively ragged, such as single-photon detectors,
 or assets where there are many relatively small data sets (e.g. scanned fluorescence data).
 
-Minimal nontrivial valid example:
-
-.. code-block:: python
-
-   # 'datum' document
-   {'resource': '272132cf-564f-428f-bf6b-149ee4287024',  # foreign key
-    'datum_kwargs': {},  # format-specific parameters
-    'datum_id': '272132cf-564f-428f-bf6b-149ee4287024/1',
-    'event_count': 1
-    }
-
 Typical example:
 
 .. code-block:: python
 
-   # datum
-   {'resource': '3b300e6f-b431-4750-a635-5630d15c81a8',
-    'datum_kwargs': {'index': 3},
-    'datum_id': '3b300e6f-b431-4750-a635-5630d15c81a8/3',
-    'event_count': 5,
-    'event_offset': 14}
-
-It is an implementation detail that ``datum_id`` is often formatted as
-``{resource}/{counter}`` but this should not be considered part of the schema.
+   # 'Stream Datum' document
+   {'uid': '86340942-9865-47f9-9a8d-bdaaab1bfce2',
+    'descriptor': '8c70b8c2-df32-40e3-9f50-29cda8142fa0',
+    'stream_resource': '272132cf-564f-428f-bf6b-149ee4287024',  # foreign key
+    'indices': {'start': 0, 'stop': 1},
+    'seq_nums': {'start': 1, 'stop': 2},
+    }
 
 Formal schema:
 

diff --git a/event_model/__init__.py b/event_model/__init__.py
@@ -1957,9 +1957,11 @@ def __call__(
             root=root,
             resource_kwargs=resource_kwargs,
             resource_path=resource_path,
-            run_start=self.start["uid"] if self.start else "",
         )
 
+        if self.start:
+            doc["run_start"] = self.start["uid"]
+
         if validate:
             schema_validators[DocumentNames.resource].validate(doc)
 
@@ -2092,9 +2094,11 @@ def __call__(
             resource_path=resource_path,
             resource_kwargs=resource_kwargs,
             path_semantics=path_semantics,
-            run_start=self.start["uid"] if self.start else "",
         )
 
+        if self.start:
+            doc["run_start"] = self.start["uid"]
+
         if validate:
             schema_validators[DocumentNames.stream_resource].validate(doc)
 
@@ -2114,7 +2118,6 @@ def compose_stream_resource(
     resource_path: str,
     data_key: str,
     resource_kwargs: Dict[str, Any],
-    counters: List = [],
     path_semantics: Literal["posix", "windows"] = default_path_semantics,
     start: Optional[RunStart] = None,
     uid: Optional[str] = None,

diff --git a/event_model/documents/resource.py b/event_model/documents/resource.py
@@ -49,10 +49,12 @@ class Resource(PartialResource):
             Field(description="Rules for joining paths"),
         ]
     ]
-    run_start: Annotated[
-        str,
-        Field(
-            description="Globally unique ID to the run_start document this "
-            "resource is associated with.",
-        ),
+    run_start: NotRequired[
+        Annotated[
+            str,
+            Field(
+                description="Globally unique ID to the run_start document this "
+                "resource is associated with.",
+            ),
+        ]
     ]