feat: update functionality for job.log with name argument (#146)

* feat(event): add/update event log with name

Can use the event's ID as its name, named events reset when a checkpoint is created

* test(event): tests for updating logs

* test(event): cleanup

* fix(event): typo for python 3.8

* fix(event): typo for python 3.8

* fix(event): review fixes

* fix(event): revert to name/id behaviour

* docs(event): better name docstring

* refactor(event): separate name and ID arguments

No longer use ID as name to reduce ambiguity

* docs(event): fix docstring typo

Author: nfrasser

cryosparc/controllers/job.py

@@ -57,6 +57,11 @@
 Input and output result groups may only contain, letters, numbers and underscores.
 """
 
+LogLevel = Literal["text", "warning", "error"]
+"""
+Severity level for job event logs.
+"""
+
 
 class JobController(Controller[Job]):
     """
@@ -108,6 +113,15 @@ class JobController(Controller[Job]):
     Project unique ID, e.g., "P3"
     """
 
+    _events: Dict[str, str]
+    """
+    Named event logs. Key can be user-provided name in log() method, or ID if
+    name not provided. If both name and ID are used, can have two keys with
+    the same value.
+
+    :meta private:
+    """
+
     def __init__(self, cs: "CryoSPARC", job: Union[Tuple[str, str], Job]) -> None:
         self.cs = cs
         if isinstance(job, tuple):
@@ -117,6 +131,7 @@ def __init__(self, cs: "CryoSPARC", job: Union[Tuple[str, str], Job]) -> None:
             self.project_uid = job.project_uid
             self.uid = job.uid
             self.model = job
+        self._events = {}
 
     @property
     def type(self) -> str:
@@ -526,24 +541,65 @@ def load_output(self, name: str, slots: LoadableSlots = "all", version: Union[in
         """
         return self.cs.api.jobs.load_output(self.project_uid, self.uid, name, slots=slots, version=version)
 
-    def log(self, text: str, level: Literal["text", "warning", "error"] = "text"):
+    @overload
+    def log(self, text: str, *, level: LogLevel = ...) -> str: ...
+    @overload
+    def log(self, text: str, *, level: LogLevel = ..., name: str) -> str: ...
+    @overload
+    def log(self, text: str, *, level: LogLevel = ..., id: str) -> str: ...
+    def log(self, text: str, *, level: LogLevel = "text", name: Optional[str] = None, id: Optional[str] = None) -> str:
         """
-        Append to a job's event log.
+        Append to a job's event log. Update an existing log by providing a name
+        or ID.
 
         Args:
             text (str): Text to log
             level (str, optional): Log level ("text", "warning" or "error").
                 Defaults to "text".
+            name (str, optional): Event name. If called multiple times with the
+                same name, updates that event instead of creating a new one.
+                Named events are reset when logging a checkpoint. Cannot be
+                provided with id. Defaults to None.
+            id (str, optional): Update a previously-created event log by its ID.
+                Cannot be provided with name. Defaults to None.
+
+        Example:
+
+            Log a warning message to the job log.
+            >>> job.log("This is a warning", level="warning")
+
+            Show a live progress bar in the job log.
+            >>> for pct in range(1, 10):
+            ...     # example log: "Progress: [#####-----] 50%"
+            ...     job.log(f"Progress: [{'#' * pct}{'-' * (10 - pct)}] {pct * 10}%", name="progress")
+            ...     sleep(1)
+            ...
+            >>> job.log("Done!")
+
+            Update an existing log event by ID.
+            >>> event_id = job.log("Starting job processing...")
+            >>> # do some processing...
+            >>> job.log("Finished processing", id=event_id)
 
         Returns:
             str: Created log event ID
         """
-        event = self.cs.api.jobs.add_event_log(self.project_uid, self.uid, text, type=level)
+        existing_id = id
+        if name and name in self._events:
+            existing_id = self._events[name]
+
+        if existing_id:
+            event = self.cs.api.jobs.update_event_log(self.project_uid, self.uid, existing_id, text, type=level)
+        else:
+            event = self.cs.api.jobs.add_event_log(self.project_uid, self.uid, text, type=level)
+
+        if name:
+            self._events[name] = event.id
         return event.id
 
     def log_checkpoint(self, meta: dict = {}):
         """
-        Append a checkpoint to the job's event log.
+        Append a checkpoint to the job's event log. Also resets named events.
 
         Args:
             meta (dict, optional): Additional meta information. Defaults to {}.
@@ -552,6 +608,7 @@ def log_checkpoint(self, meta: dict = {}):
             str: Created checkpoint event ID
         """
         event = self.cs.api.jobs.add_checkpoint(self.project_uid, self.uid, meta)
+        self._events = {}
         return event.id
 
     def log_plot(

tests/controllers/test_job.py

@@ -80,7 +80,6 @@ def test_job_subprocess_io(job: JobController):
         [sys.executable, "-c", 'import sys; print("hello"); print("error", file=sys.stderr); print("world")']
     )
 
-    assert len(mock_log_endpoint.mock_calls) == 7  # includes some prelude/divider calls
     mock_log_endpoint.assert_has_calls(
         [
             mock.call(job.project_uid, job.uid, "hello", type="text"),
@@ -185,3 +184,85 @@ def test_external_job_output(mock_external_job_with_saved_output: ExternalJobCon
 def test_invalid_external_job_output(external_job):
     with pytest.raises(ValueError, match="Invalid output name"):
         external_job.add_output("particle", name="particles/1", slots=["blob", "ctf"])
+
+
+@pytest.fixture
+def mock_log_event():
+    return mock.MagicMock(id="event_123")
+
+
+@pytest.fixture
+def mock_checkpoint_event():
+    return mock.MagicMock(id="checkpoint_456")
+
+
+def test_log(job: JobController, mock_log_event):
+    assert isinstance(mock_add_endpoint := APIClient.jobs.add_event_log, mock.Mock)
+    mock_add_endpoint.return_value = mock_log_event
+
+    result = job.log("Test message without name")
+
+    mock_add_endpoint.assert_called_once_with(job.project_uid, job.uid, "Test message without name", type="text")
+    assert result == mock_log_event.id
+
+
+def test_log_with_name_create_and_update(job: JobController, mock_log_event):
+    assert isinstance(mock_add_endpoint := APIClient.jobs.add_event_log, mock.Mock)
+    assert isinstance(mock_update_endpoint := APIClient.jobs.update_event_log, mock.Mock)
+    mock_add_endpoint.return_value = mock_log_event
+    mock_update_endpoint.return_value = mock_log_event
+
+    # First call with name - should create
+    event_id = job.log("First message", name="progress")
+
+    mock_add_endpoint.assert_called_once_with(job.project_uid, job.uid, "First message", type="text")
+    assert event_id == "event_123"
+
+    # Second call with same name - should update
+    event_id = job.log("Updated message", level="warning", name="progress")
+
+    mock_update_endpoint.assert_called_once_with(
+        job.project_uid, job.uid, mock_log_event.id, "Updated message", type="warning"
+    )
+    assert event_id == "event_123"
+
+
+def test_log_with_returned_event_id(job: JobController, mock_log_event):
+    assert isinstance(mock_add_endpoint := APIClient.jobs.add_event_log, mock.Mock)
+    assert isinstance(mock_update_endpoint := APIClient.jobs.update_event_log, mock.Mock)
+    mock_add_endpoint.return_value = mock_log_event
+    mock_update_endpoint.return_value = mock_log_event
+
+    # First call without ID - returns event ID
+    event_id = job.log("Initial message")
+    assert event_id == mock_log_event.id
+
+    # Second call using the returned event ID - should update
+    result = job.log("Updated with event ID", id=event_id)
+
+    mock_update_endpoint.assert_called_once_with(
+        job.project_uid, job.uid, mock_log_event.id, "Updated with event ID", type="text"
+    )
+    assert result == event_id
+
+
+def test_log_after_checkpoint_creates_new(job: JobController, mock_log_event, mock_checkpoint_event):
+    assert isinstance(mock_add_endpoint := APIClient.jobs.add_event_log, mock.Mock)
+    assert isinstance(mock_update_endpoint := APIClient.jobs.update_event_log, mock.Mock)
+    assert isinstance(mock_checkpoint_endpoint := APIClient.jobs.add_checkpoint, mock.Mock)
+
+    mock_add_endpoint.return_value = mock_log_event
+    mock_update_endpoint.return_value = mock_log_event
+    mock_checkpoint_endpoint.return_value = mock_checkpoint_event
+
+    job.log("Before checkpoint", name="status")
+
+    checkpoint_id = job.log_checkpoint()
+    mock_checkpoint_endpoint.assert_called_once_with(job.project_uid, job.uid, {})
+    assert checkpoint_id == mock_checkpoint_event.id
+
+    # Log again with same name - should create new
+    mock_add_endpoint.reset_mock()  # Reset to track the second call
+    result = job.log("After checkpoint", name="status")
+    mock_add_endpoint.assert_called_once_with(job.project_uid, job.uid, "After checkpoint", type="text")
+    assert result == "event_123"