docs(events): update event docstrings

invokeai/app/services/events/events_base.py

@@ -56,6 +56,7 @@ class EventServiceBase:
     # region: Invocation
 
     def emit_invocation_started(self, queue_item: "SessionQueueItem", invocation: "BaseInvocation") -> None:
+        """Emitted when an invocation is started"""
         self.dispatch(InvocationStartedEvent.build(queue_item, invocation))
 
     def emit_invocation_denoise_progress(
@@ -66,11 +67,13 @@ class EventServiceBase:
         total_steps: int,
         progress_image: "ProgressImage",
     ) -> None:
+        """Emitted at each step during denoising of an invocation."""
         self.dispatch(InvocationDenoiseProgressEvent.build(queue_item, invocation, step, total_steps, progress_image))
 
     def emit_invocation_complete(
         self, queue_item: "SessionQueueItem", invocation: "BaseInvocation", output: "BaseInvocationOutput"
     ) -> None:
+        """Emitted when an invocation is complete"""
         self.dispatch(InvocationCompleteEvent.build(queue_item, invocation, output))
 
     def emit_invocation_error(
@@ -81,6 +84,7 @@ class EventServiceBase:
         error_message: str,
         error_traceback: str,
     ) -> None:
+        """Emitted when an invocation encounters an error"""
         self.dispatch(InvocationErrorEvent.build(queue_item, invocation, error_type, error_message, error_traceback))
 
     # endregion
@@ -88,12 +92,15 @@ class EventServiceBase:
     # region Session
 
     def emit_session_started(self, queue_item: "SessionQueueItem") -> None:
+        """Emitted when a session has started"""
         self.dispatch(SessionStartedEvent.build(queue_item))
 
     def emit_session_complete(self, queue_item: "SessionQueueItem") -> None:
+        """Emitted when a session has completed all invocations"""
         self.dispatch(SessionCompleteEvent.build(queue_item))
 
     def emit_session_canceled(self, queue_item: "SessionQueueItem") -> None:
+        """Emitted when a session is canceled"""
         self.dispatch(SessionCanceledEvent.build(queue_item))
 
     # endregion
@@ -103,12 +110,15 @@ class EventServiceBase:
     def emit_queue_item_status_changed(
         self, queue_item: "SessionQueueItem", batch_status: "BatchStatus", queue_status: "SessionQueueStatus"
     ) -> None:
+        """Emitted when a queue item's status changes"""
         self.dispatch(QueueItemStatusChangedEvent.build(queue_item, batch_status, queue_status))
 
     def emit_batch_enqueued(self, enqueue_result: "EnqueueBatchResult") -> None:
+        """Emitted when a batch is enqueued"""
         self.dispatch(BatchEnqueuedEvent.build(enqueue_result))
 
     def emit_queue_cleared(self, queue_id: str) -> None:
+        """Emitted when a queue is cleared"""
         self.dispatch(QueueClearedEvent.build(queue_id))
 
     # endregion
@@ -116,18 +126,23 @@ class EventServiceBase:
     # region Download
 
     def emit_download_started(self, source: str, download_path: str) -> None:
+        """Emitted when a download is started"""
         self.dispatch(DownloadStartedEvent.build(source, download_path))
 
     def emit_download_progress(self, source: str, download_path: str, current_bytes: int, total_bytes: int) -> None:
+        """Emitted at intervals during a download"""
         self.dispatch(DownloadProgressEvent.build(source, download_path, current_bytes, total_bytes))
 
     def emit_download_complete(self, source: str, download_path: str, total_bytes: int) -> None:
+        """Emitted when a download is completed"""
         self.dispatch(DownloadCompleteEvent.build(source, download_path, total_bytes))
 
     def emit_download_cancelled(self, source: str) -> None:
+        """Emitted when a download is cancelled"""
         self.dispatch(DownloadCancelledEvent.build(source))
 
     def emit_download_error(self, source: str, error_type: str, error: str) -> None:
+        """Emitted when a download encounters an error"""
         self.dispatch(DownloadErrorEvent.build(source, error_type, error))
 
     # endregion
@@ -135,11 +150,13 @@ class EventServiceBase:
     # region Model loading
 
     def emit_model_load_started(self, config: "AnyModelConfig", submodel_type: Optional["SubModelType"] = None) -> None:
+        """Emitted when a model load is started."""
         self.dispatch(ModelLoadStartedEvent.build(config, submodel_type))
 
     def emit_model_load_complete(
         self, config: "AnyModelConfig", submodel_type: Optional["SubModelType"] = None
     ) -> None:
+        """Emitted when a model load is complete."""
         self.dispatch(ModelLoadCompleteEvent.build(config, submodel_type))
 
     # endregion
@@ -147,21 +164,26 @@ class EventServiceBase:
     # region Model install
 
     def emit_model_install_download_progress(self, job: "ModelInstallJob") -> None:
+        """Emitted at intervals while the install job is in progress (remote models only)."""
         self.dispatch(ModelInstallDownloadProgressEvent.build(job))
 
     def emit_model_install_downloads_complete(self, job: "ModelInstallJob") -> None:
         self.dispatch(ModelInstallDownloadsCompleteEvent.build(job))
 
     def emit_model_install_started(self, job: "ModelInstallJob") -> None:
+        """Emitted once when an install job is started (after any download)."""
         self.dispatch(ModelInstallStartedEvent.build(job))
 
     def emit_model_install_complete(self, job: "ModelInstallJob") -> None:
+        """Emitted when an install job is completed successfully."""
         self.dispatch(ModelInstallCompleteEvent.build(job))
 
     def emit_model_install_cancelled(self, job: "ModelInstallJob") -> None:
+        """Emitted when an install job is cancelled."""
         self.dispatch(ModelInstallCancelledEvent.build(job))
 
     def emit_model_install_error(self, job: "ModelInstallJob") -> None:
+        """Emitted when an install job encounters an exception."""
         self.dispatch(ModelInstallErrorEvent.build(job))
 
     # endregion
@@ -171,16 +193,19 @@ class EventServiceBase:
     def emit_bulk_download_started(
         self, bulk_download_id: str, bulk_download_item_id: str, bulk_download_item_name: str
     ) -> None:
+        """Emitted when a bulk image download is started"""
         self.dispatch(BulkDownloadStartedEvent.build(bulk_download_id, bulk_download_item_id, bulk_download_item_name))
 
     def emit_bulk_download_complete(
         self, bulk_download_id: str, bulk_download_item_id: str, bulk_download_item_name: str
     ) -> None:
+        """Emitted when a bulk image download is complete"""
         self.dispatch(BulkDownloadCompleteEvent.build(bulk_download_id, bulk_download_item_id, bulk_download_item_name))
 
     def emit_bulk_download_error(
         self, bulk_download_id: str, bulk_download_item_id: str, bulk_download_item_name: str, error: str
     ) -> None:
+        """Emitted when a bulk image download has an error"""
         self.dispatch(
             BulkDownloadErrorEvent.build(bulk_download_id, bulk_download_item_id, bulk_download_item_name, error)
         )

invokeai/app/services/events/events_common.py

@@ -93,7 +93,7 @@ class InvocationEventBase(SessionEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class InvocationStartedEvent(InvocationEventBase):
-    """Emitted when an invocation is started"""
+    """Event model for invocation_started"""
 
     __event_name__ = "invocation_started"
 
@@ -112,7 +112,7 @@ class InvocationStartedEvent(InvocationEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class InvocationDenoiseProgressEvent(InvocationEventBase):
-    """Emitted at each step during denoising of an invocation."""
+    """Event model for invocation_denoise_progress"""
 
     __event_name__ = "invocation_denoise_progress"
 
@@ -145,7 +145,7 @@ class InvocationDenoiseProgressEvent(InvocationEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class InvocationCompleteEvent(InvocationEventBase):
-    """Emitted when an invocation is complete"""
+    """Event model for invocation_complete"""
 
     __event_name__ = "invocation_complete"
 
@@ -169,7 +169,7 @@ class InvocationCompleteEvent(InvocationEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class InvocationErrorEvent(InvocationEventBase):
-    """Emitted when an invocation encounters an error"""
+    """Event model for invocation_error"""
 
     __event_name__ = "invocation_error"
 
@@ -202,7 +202,7 @@ class InvocationErrorEvent(InvocationEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class SessionStartedEvent(SessionEventBase):
-    """Emitted when a session has started"""
+    """Event model for session_started"""
 
     __event_name__ = "session_started"
 
@@ -218,7 +218,7 @@ class SessionStartedEvent(SessionEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class SessionCompleteEvent(SessionEventBase):
-    """Emitted when a session has completed all invocations"""
+    """Event model for session_complete"""
 
     __event_name__ = "session_complete"
 
@@ -234,7 +234,7 @@ class SessionCompleteEvent(SessionEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class SessionCanceledEvent(SessionEventBase):
-    """Emitted when a session is canceled"""
+    """Event model for session_canceled"""
 
     __event_name__ = "session_canceled"
 
@@ -249,8 +249,8 @@ class SessionCanceledEvent(SessionEventBase):
 
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
-class QueueItemStatusChangedEvent(SessionEventBase):
-    """Emitted when a queue item's status changes"""
+class QueueItemStatusChangedEvent(QueueItemEventBase):
+    """Event model for queue_item_status_changed"""
 
     __event_name__ = "queue_item_status_changed"
 
@@ -264,6 +264,7 @@ class QueueItemStatusChangedEvent(SessionEventBase):
     completed_at: Optional[str] = Field(default=None, description="The timestamp when the queue item was completed")
     batch_status: BatchStatus = Field(description="The status of the batch")
     queue_status: SessionQueueStatus = Field(description="The status of the queue")
+    session_id: str = Field(description="The ID of the session (aka graph execution state)")
 
     @classmethod
     def build(
@@ -289,7 +290,7 @@ class QueueItemStatusChangedEvent(SessionEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class BatchEnqueuedEvent(QueueEventBase):
-    """Emitted when a batch is enqueued"""
+    """Event model for batch_enqueued"""
 
     __event_name__ = "batch_enqueued"
 
@@ -313,7 +314,7 @@ class BatchEnqueuedEvent(QueueEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class QueueClearedEvent(QueueEventBase):
-    """Emitted when a queue is cleared"""
+    """Event model for queue_cleared"""
 
     __event_name__ = "queue_cleared"
 
@@ -330,7 +331,7 @@ class DownloadEventBase(EventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class DownloadStartedEvent(DownloadEventBase):
-    """Emitted when a download is started"""
+    """Event model for download_started"""
 
     __event_name__ = "download_started"
 
@@ -343,7 +344,7 @@ class DownloadStartedEvent(DownloadEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class DownloadProgressEvent(DownloadEventBase):
-    """Emitted at intervals during a download"""
+    """Event model for download_progress"""
 
     __event_name__ = "download_progress"
 
@@ -358,7 +359,7 @@ class DownloadProgressEvent(DownloadEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class DownloadCompleteEvent(DownloadEventBase):
-    """Emitted when a download is completed"""
+    """Event model for download_complete"""
 
     __event_name__ = "download_complete"
 
@@ -372,7 +373,7 @@ class DownloadCompleteEvent(DownloadEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class DownloadCancelledEvent(DownloadEventBase):
-    """Emitted when a download is cancelled"""
+    """Event model for download_cancelled"""
 
     __event_name__ = "download_cancelled"
 
@@ -383,7 +384,7 @@ class DownloadCancelledEvent(DownloadEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class DownloadErrorEvent(DownloadEventBase):
-    """Emitted when a download encounters an error"""
+    """Event model for download_error"""
 
     __event_name__ = "download_error"
 
@@ -401,7 +402,7 @@ class ModelEventBase(EventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class ModelLoadStartedEvent(ModelEventBase):
-    """Emitted when a model is requested"""
+    """Event model for model_load_started"""
 
     __event_name__ = "model_load_started"
 
@@ -415,7 +416,7 @@ class ModelLoadStartedEvent(ModelEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class ModelLoadCompleteEvent(ModelEventBase):
-    """Emitted when a model is requested"""
+    """Event model for model_load_complete"""
 
     __event_name__ = "model_load_complete"
 
@@ -429,7 +430,7 @@ class ModelLoadCompleteEvent(ModelEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class ModelInstallDownloadProgressEvent(ModelEventBase):
-    """Emitted at intervals while the install job is in progress (remote models only)."""
+    """Event model for model_install_download_progress"""
 
     __event_name__ = "model_install_download_progress"
 
@@ -479,7 +480,7 @@ class ModelInstallDownloadsCompleteEvent(ModelEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class ModelInstallStartedEvent(ModelEventBase):
-    """Emitted once when an install job becomes active."""
+    """Event model for model_install_started"""
 
     __event_name__ = "model_install_started"
 
@@ -493,7 +494,7 @@ class ModelInstallStartedEvent(ModelEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class ModelInstallCompleteEvent(ModelEventBase):
-    """Emitted when an install job is completed successfully."""
+    """Event model for model_install_complete"""
 
     __event_name__ = "model_install_complete"
 
@@ -510,7 +511,7 @@ class ModelInstallCompleteEvent(ModelEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class ModelInstallCancelledEvent(ModelEventBase):
-    """Emitted when an install job is cancelled."""
+    """Event model for model_install_cancelled"""
 
     __event_name__ = "model_install_cancelled"
 
@@ -524,7 +525,7 @@ class ModelInstallCancelledEvent(ModelEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class ModelInstallErrorEvent(ModelEventBase):
-    """Emitted when an install job encounters an exception."""
+    """Event model for model_install_error"""
 
     __event_name__ = "model_install_error"
 
@@ -550,7 +551,7 @@ class BulkDownloadEventBase(EventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class BulkDownloadStartedEvent(BulkDownloadEventBase):
-    """Emitted when a bulk image download is started"""
+    """Event model for bulk_download_started"""
 
     __event_name__ = "bulk_download_started"
 
@@ -567,7 +568,7 @@ class BulkDownloadStartedEvent(BulkDownloadEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class BulkDownloadCompleteEvent(BulkDownloadEventBase):
-    """Emitted when a bulk image download is started"""
+    """Event model for bulk_download_complete"""
 
     __event_name__ = "bulk_download_complete"
 
@@ -584,7 +585,7 @@ class BulkDownloadCompleteEvent(BulkDownloadEventBase):
 
 @payload_schema.register  # pyright: ignore [reportUnknownMemberType]
 class BulkDownloadErrorEvent(BulkDownloadEventBase):
-    """Emitted when a bulk image download is started"""
+    """Event model for bulk_download_error"""
 
     __event_name__ = "bulk_download_error"