name photos

Author: CamDavidsonPilon

core/pioreactor/actions/camera_snapshot.py

@@ -3,6 +3,7 @@
 from pioreactor import types as pt
 from pioreactor import whoami
 from pioreactor.camera import camera_still_image_path
+from pioreactor.camera import camera_storage_name_is_safe
 from pioreactor.camera import CameraCaptureError
 from pioreactor.camera import CameraStillMetadata
 from pioreactor.camera import CameraUnavailableError
@@ -13,20 +14,30 @@
 def camera_snapshot(
     unit: pt.Unit | None = None,
     experiment: pt.Experiment | None = None,
+    name: str | None = None,
 ) -> CameraStillMetadata:
     """Capture and store a still for the unit's assigned experiment."""
+    if name is not None and not camera_storage_name_is_safe(name):
+        raise ValueError(f"Unsafe camera image name: {name}")
+
     unit = unit or whoami.get_unit_name()
     experiment = experiment or whoami.get_assigned_experiment_name(unit)
 
     with managed_lifecycle(unit, experiment, "camera_snapshot"):
-        return capture_camera_still(unit, experiment=experiment, capture_reason="manual")
+        return capture_camera_still(
+            unit,
+            experiment=experiment,
+            capture_reason="manual",
+            image_id=name,
+        )
 
 
 @click.command(name="camera_snapshot")
-def click_camera_snapshot() -> None:
+@click.option("--name", help="Photo name without the .jpg extension.")
+def click_camera_snapshot(name: str | None) -> None:
     """Take a camera snapshot for the current experiment."""
     try:
-        metadata = camera_snapshot()
+        metadata = camera_snapshot(name=name)
     except (CameraUnavailableError, CameraCaptureError, ValueError) as error:
         raise click.ClickException(str(error)) from error
 

core/pioreactor/camera.py

@@ -811,6 +811,7 @@ def capture_camera_still(
     *,
     experiment: pt.Experiment | None,
     capture_reason: CameraCaptureReason,
+    image_id: str | None = None,
     timeout: float = 20.0,
     dot_pioreactor: Path | None = None,
 ) -> CameraStillMetadata:
@@ -826,6 +827,7 @@ def capture_camera_still(
             unit,
             experiment=experiment,
             capture_reason=capture_reason,
+            image_id=image_id,
             dot_pioreactor=dot_pioreactor,
         )
 

core/tests/test_camera_snapshot.py

@@ -26,10 +26,17 @@ def test_camera_snapshot_uses_current_unit_and_experiment(monkeypatch: pytest.Mo
     )
     monkeypatch.setattr(camera_snapshot, "managed_lifecycle", lifecycle)
 
-    def capture(unit: str, *, experiment: str | None, capture_reason: str) -> CameraStillMetadata:
+    def capture(
+        unit: str,
+        *,
+        experiment: str | None,
+        capture_reason: str,
+        image_id: str | None,
+    ) -> CameraStillMetadata:
         captured["unit"] = unit
         captured["experiment"] = experiment
         captured["capture_reason"] = capture_reason
+        captured["image_id"] = image_id
         return metadata
 
     monkeypatch.setattr(camera_snapshot, "capture_camera_still", capture)
@@ -39,5 +46,42 @@ def capture(unit: str, *, experiment: str | None, capture_reason: str) -> Camera
         "unit": "unit-a",
         "experiment": "experiment-a",
         "capture_reason": "manual",
+        "image_id": None,
     }
     lifecycle.assert_called_once_with("unit-a", "experiment-a", "camera_snapshot")
+
+
+def test_camera_snapshot_passes_name_as_image_id(monkeypatch: pytest.MonkeyPatch) -> None:
+    metadata = CameraStillMetadata(
+        experiment="experiment-a",
+        captured_at=datetime(2026, 7, 13, 12, 0, tzinfo=UTC),
+        image_id="inoculation",
+    )
+    captured: dict[str, str | None] = {}
+
+    monkeypatch.setattr(camera_snapshot, "managed_lifecycle", lambda *_args: nullcontext())
+
+    def capture(
+        unit: str,
+        *,
+        experiment: str | None,
+        capture_reason: str,
+        image_id: str | None,
+    ) -> CameraStillMetadata:
+        captured["image_id"] = image_id
+        return metadata
+
+    monkeypatch.setattr(camera_snapshot, "capture_camera_still", capture)
+
+    assert camera_snapshot.camera_snapshot("unit-a", "experiment-a", name="inoculation") == metadata
+    assert captured["image_id"] == "inoculation"
+
+
+def test_camera_snapshot_rejects_unsafe_name_before_capture(monkeypatch: pytest.MonkeyPatch) -> None:
+    capture = MagicMock()
+    monkeypatch.setattr(camera_snapshot, "capture_camera_still", capture)
+
+    with pytest.raises(ValueError, match="Unsafe camera image name"):
+        camera_snapshot.camera_snapshot("unit-a", "experiment-a", name="../inoculation")
+
+    capture.assert_not_called()

core/tests/test_cli.py

@@ -1142,11 +1142,18 @@ def test_camera_snapshot(monkeypatch: pytest.MonkeyPatch) -> None:
         captured_at=datetime(2026, 7, 13, 12, 0, tzinfo=UTC),
         image_id="image-a",
     )
-    monkeypatch.setattr(camera_snapshot, "camera_snapshot", lambda: metadata)
+    supplied_names: list[str | None] = []
 
-    result = CliRunner().invoke(pio, ["run", "camera_snapshot"])
+    def capture(name: str | None) -> CameraStillMetadata:
+        supplied_names.append(name)
+        return metadata
+
+    monkeypatch.setattr(camera_snapshot, "camera_snapshot", capture)
+
+    result = CliRunner().invoke(pio, ["run", "camera_snapshot", "--name", "inoculation"])
 
     assert result.exit_code == 0
+    assert supplied_names == ["inoculation"]
     expected_path = camera_snapshot.camera_still_image_path(metadata)
     assert result.output == f"Captured camera snapshot image-a, at {expected_path}\n"
 
@@ -1155,7 +1162,7 @@ def test_camera_snapshot_reports_capture_error(monkeypatch: pytest.MonkeyPatch)
     from pioreactor.actions import camera_snapshot
     from pioreactor.camera import CameraUnavailableError
 
-    def raise_camera_unavailable() -> None:
+    def raise_camera_unavailable(name: str | None) -> None:
         raise CameraUnavailableError("No camera detected.")
 
     monkeypatch.setattr(camera_snapshot, "camera_snapshot", raise_camera_unavailable)