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(