Document entrypoint functions

Author: dandavison

temporalio/client.py

@@ -851,6 +851,40 @@ async def execute_update_with_start(  # type: ignore
         rpc_metadata: Mapping[str, str] = {},
         rpc_timeout: Optional[timedelta] = None,
     ) -> Any:
+        """Send an update-with-start request and wait for the update to complete.
+
+        A WorkflowIDConflictPolicy must be set in the start_workflow_operation. If the
+        specified workflow execution is not running, a new workflow execution is started
+        and the update is sent in the first workflow task. Alternatively if the specified
+        workflow execution is running then, if the WorkflowIDConflictPolicy is
+        USE_EXISTING, the update is issued against the specified workflow, and if the
+        WorkflowIDConflictPolicy is FAIL, an error is returned. This call will block until
+        the update has completed, and return the update result. Note that this means that
+        the call will not return successfully until the update has been delivered to a
+        worker.
+
+        Args:
+            update: Update function or name on the workflow. arg: Single argument to the
+            update. args: Multiple arguments to the update. Cannot be set if arg is.
+            start_workflow_operation: a WithStartWorkflowOperation definining the
+                WorkflowIDConflictPolicy and how to start the workflow in the event that a
+                workflow is started.
+            id: ID of the update. If not set, the default is a new UUID. result_type: For
+            string updates, this can set the specific result
+                type hint to deserialize into.
+            rpc_metadata: Headers used on the RPC call. Keys here override
+                client-level RPC metadata keys.
+            rpc_timeout: Optional RPC deadline to set for the RPC call.
+
+        Raises:
+            WorkflowUpdateFailedError: If the update failed.
+            WorkflowUpdateRPCTimeoutOrCancelledError: This update call timed out
+                or was cancelled. This doesn't mean the update itself was timed out or
+                cancelled.
+
+            RPCError: There was some issue starting the workflow or sending the update to
+                the workflow.
+        """
         handle = await self._start_update_with_start(
             update,
             arg,
@@ -940,6 +974,43 @@ async def start_update_with_start(  # type: ignore
         rpc_metadata: Mapping[str, str] = {},
         rpc_timeout: Optional[timedelta] = None,
     ) -> WorkflowUpdateHandle[Any]:
+        """Send an update-with-start request and wait for it to be accepted.
+
+        A WorkflowIDConflictPolicy must be set in the start_workflow_operation. If the
+        specified workflow execution is not running, a new workflow execution is started
+        and the update is sent in the first workflow task. Alternatively if the specified
+        workflow execution is running then, if the WorkflowIDConflictPolicy is
+        USE_EXISTING, the update is issued against the specified workflow, and if the
+        WorkflowIDConflictPolicy is FAIL, an error is returned. This call will block until
+        the update has been accepted, and return a WorkflowUpdateHandle. Note that this
+        means that the call will not return successfully until the update has been
+        delivered to a worker.
+
+        Args:
+            update: Update function or name on the workflow. arg: Single argument to the
+            update. args: Multiple arguments to the update. Cannot be set if arg is.
+            start_workflow_operation: a WithStartWorkflowOperation definining the
+                WorkflowIDConflictPolicy and how to start the workflow in the event that a
+                workflow is started.
+            wait_for_stage: Required stage to wait until returning: either ACCEPTED or
+                COMPLETED. ADMITTED is not currently supported. See
+                https://docs.temporal.io/workflows#update for more details.
+            id: ID of the update. If not set, the default is a new UUID. result_type: For
+            string updates, this can set the specific result
+                type hint to deserialize into.
+            rpc_metadata: Headers used on the RPC call. Keys here override
+                client-level RPC metadata keys.
+            rpc_timeout: Optional RPC deadline to set for the RPC call.
+
+        Raises:
+            WorkflowUpdateFailedError: If the update failed.
+            WorkflowUpdateRPCTimeoutOrCancelledError: This update call timed out
+                or was cancelled. This doesn't mean the update itself was timed out or
+                cancelled.
+
+            RPCError: There was some issue starting the workflow or sending the update to
+                the workflow.
+        """
         return await self._start_update_with_start(
             update,
             arg,
@@ -2186,23 +2257,23 @@ async def start_update(
             unrelated to the started workflow.
 
         Args:
-            update: Update function or name on the workflow.
-            arg: Single argument to the update.
-            wait_for_stage: Required stage to wait until returning. ADMITTED is
-                not currently supported. See https://docs.temporal.io/workflows#update
-                for more details.
-            args: Multiple arguments to the update. Cannot be set if arg is.
-            id: ID of the update. If not set, the default is a new UUID.
-            result_type: For string updates, this can set the specific result
+            update: Update function or name on the workflow. arg: Single argument to the
+            update.
+            wait_for_stage: Required stage to wait until returning: either ACCEPTED or
+                COMPLETED. ADMITTED is not currently supported. See
+                https://docs.temporal.io/workflows#update for more details.
+            args: Multiple arguments to the update. Cannot be set if arg is. id: ID of the
+            update. If not set, the default is a new UUID. result_type: For string
+            updates, this can set the specific result
                 type hint to deserialize into.
             rpc_metadata: Headers used on the RPC call. Keys here override
                 client-level RPC metadata keys.
             rpc_timeout: Optional RPC deadline to set for the RPC call.
 
         Raises:
             WorkflowUpdateRPCTimeoutOrCancelledError: This update call timed out
-                or was cancelled. This doesn't mean the update itself was timed
-                out or cancelled.
+                or was cancelled. This doesn't mean the update itself was timed out or
+                cancelled.
             RPCError: There was some issue sending the update to the workflow.
         """
         return await self._start_update(
@@ -2321,8 +2392,7 @@ def get_update_handle_for(
 
 
 class WithStartWorkflowOperation(Generic[SelfType, ReturnType]):
-    """
-    Defines a start-workflow operation used by update-with-start requests.
+    """Defines a start-workflow operation used by update-with-start requests.
 
     Update-With-Start allows you to send an update to a workflow, while starting the
     workflow if necessary.
@@ -2471,8 +2541,7 @@ def __init__(
         rpc_timeout: Optional[timedelta] = None,
         stack_level: int = 2,
     ) -> None:
-        """
-        Create a WithStartWorkflowOperation.
+        """Create a WithStartWorkflowOperation.
 
         See :py:meth:`temporalio.client.Client.start_workflow` for documentation of the
         arguments.
@@ -2507,6 +2576,7 @@ def __init__(
         self._workflow_handle: Future[WorkflowHandle[SelfType, ReturnType]] = Future()
 
     async def workflow_handle(self) -> WorkflowHandle[SelfType, ReturnType]:
+        """Return the WorkflowHandle once the workflow is running."""
         return await self._workflow_handle
 
 
@@ -5397,8 +5467,7 @@ async def start_workflow_update(
     async def start_workflow_update_with_start(
         self, input: StartWorkflowUpdateWithStartInput
     ) -> WorkflowUpdateHandle[Any]:
-        """Called for every :py:meth:`Client.start_update_with_start` and
-        :py:meth:`Client.execute_update_with_start` call."""
+        """Called for every :py:meth:`Client.start_update_with_start` and :py:meth:`Client.execute_update_with_start` call."""
         return await self.next.start_workflow_update_with_start(input)
 
     ### Async activity calls