refactor(event): separate name and ID arguments

No longer use ID as name to reduce ambiguity

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]):
     """
@@ -536,19 +541,27 @@ 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", name: Optional[str] = None):
+    @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. Update an existing log by providing a name.
+        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 or ID. If called multiple times
-                with the same name, updates that event instead of creating a new
-                one. If name is not initially provided, can pass returned ID as
-                name. Named events are reset when logging a checkpoint.
-                Defaults to None.
+            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:
 
@@ -569,15 +582,20 @@ def log(self, text: str, *, level: Literal["text", "warning", "error"] = "text",
             >>> job.log("Finished processing", name=event_id)
 
         Returns:
-            str: Created log event name or ID
+            str: Created log event ID
         """
+        existing_id = id
         if name and name in self._events:
-            event_id = self._events[name]
-            event = self.cs.api.jobs.update_event_log(self.project_uid, self.uid, event_id, text, type=level)
+            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)
-            self._events[name or event.id] = event.id
-        return name or event.id
+
+        if name:
+            self._events[name] = event.id
+        return event.id
 
     def log_checkpoint(self, meta: dict = {}):
         """

tests/controllers/test_job.py

@@ -196,7 +196,7 @@ def mock_checkpoint_event():
     return mock.MagicMock(id="checkpoint_456")
 
 
-def test_log_without_name(job: JobController, mock_log_event):
+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
 
@@ -213,32 +213,32 @@ def test_log_with_name_create_and_update(job: JobController, mock_log_event):
     mock_update_endpoint.return_value = mock_log_event
 
     # First call with name - should create
-    result1 = job.log("First message", name="progress")
+    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 result1 == "progress"
+    assert event_id == "event_123"
 
     # Second call with same name - should update
-    result2 = job.log("Updated message", level="warning", name="progress")
+    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 result2 == "progress"
+    assert event_id == "event_123"
 
 
-def test_log_with_returned_event_id_as_name(job: JobController, mock_log_event):
+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 name - returns event ID
+    # 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 as name - should update
-    result = job.log("Updated with event ID", name=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"
@@ -265,4 +265,4 @@ def test_log_after_checkpoint_creates_new(job: JobController, mock_log_event, mo
     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 == "status"
+    assert result == "event_123"