EDU-3715: Python update-with-start docs

docs/develop/go/message-passing.mdx

@@ -380,7 +380,7 @@ Minimum Temporal Server version [Temporal Server version 1.26](https://github.co
 [send an Update](/develop/go/message-passing#send-update-from-client) that checks whether an already-running Workflow with that ID exists:
 
 - If the Workflow exists, the Update is processed.
-- If the Workflow does not exist, a new Workflow Execution starts with the given ID, and the Update is processed immediately after.
+- If the Workflow does not exist, a new Workflow Execution is started with the given ID, and the Update is processed immediately after.
 
 Use the [`Client.UpdateWithStartWorkflow`](https://pkg.go.dev/go.temporal.io/sdk/client#Client.UpdateWithStartWorkflow) API call.
 It returns once the requested Update wait stage has been reached; or when a provided context times out.
@@ -403,8 +403,8 @@ You will need to provide:
 
 - [`Client.NewWithStartWorkflowOperation`](https://pkg.go.dev/go.temporal.io/sdk/client#Client.NewWithStartWorkflowOperation).
   Specify the workflow options, method and arguments.
-  Note that a `WithStartWorkflowOperation` can only be executed once.
-  Re-using a previously executed operation returns an error from `UpdateWithStartWorkflow`.
+  Note that a `WithStartWorkflowOperation` can only be used once.
+  Re-using a previously used operation returns an error from `UpdateWithStartWorkflow`.
 
 The following example shows the creation, configuration, and use of UpdateWithStart:
 

docs/develop/java/message-passing.mdx

@@ -398,7 +398,7 @@ Minimum Temporal Server version [Temporal Server version 1.26](https://github.co
 [send an Update](/develop/java/message-passing#send-update-from-client) that checks whether an already-running Workflow with that ID exists:
 
 - If the Workflow exists, the Update is processed.
-- If the Workflow does not exist, a new Workflow Execution starts with the given ID, and the Update is processed immediately after.
+- If the Workflow does not exist, a new Workflow Execution is started with the given ID, and the Update is processed immediately after.
 
 Use the [`startUpdateWithStart`](https://javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/WorkflowClient.html#startUpdateWithStart(io.temporal.workflow.Functions.Func,io.temporal.client.UpdateOptions,io.temporal.client.WithStartWorkflowOperation)) WorkflowClient API.
 It returns once the requested Update wait stage has been reached; or when the request times out.
@@ -420,8 +420,8 @@ You will need to provide:
 
 - [`WithStartWorkflowOperation`](https://javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/WithStartWorkflowOperation.html).
   Specify the workflow method.
-  Note that a `WithStartWorkflowOperation` can only be executed once.
-  Re-using a previously executed operation returns an error from `startUpdateWithStart`.
+  Note that a `WithStartWorkflowOperation` can only be used once.
+  Re-using a previously used operation returns an error from `startUpdateWithStart`.
 
 For example:
 

docs/develop/python/message-passing.mdx

@@ -317,6 +317,60 @@ To obtain an Update handle, you can:
 - Use [`start_update`](https://python.temporal.io/temporalio.client.WorkflowHandle.html#start_update) to start an Update and return the handle, as shown in the preceding example.
 - Use [`get_update_handle_for`](https://python.temporal.io/temporalio.client.WorkflowHandle.html#get_update_handle_for) to fetch a handle for an in-progress Update using the Update ID.
 
+
+#### Update-With-Start {#update-with-start}
+
+:::tip Stability
+
+In [Public Preview](/evaluate/development-production-features/release-stages#public-preview) in Temporal Cloud.
+
+Minimum Temporal Server version [Temporal Server version 1.26](https://github.com/temporalio/temporal/releases/tag/v1.26.0)
+
+:::
+
+[Update-with-Start](/encyclopedia/workflow-message-passing#update-with-start) lets you
+[send an Update](/develop/python/message-passing#send-update-from-client) that checks whether an already-running Workflow with that ID exists:
+
+- If the Workflow exists, the Update is processed.
+- If the Workflow does not exist, a new Workflow Execution is started with the given ID, and the Update is processed immediately after.
+
+Use [`execute_update_with_start_workflow`](https://python.temporal.io/temporalio.client.Client.html#start_update_with_start_workflow) to start the Update and wait for the result in one go.
+
+Alternatively, use [`start_update_with_start_workflow`](https://python.temporal.io/temporalio.client.Client.html#start_update_with_start_workflow) to start the Update and receive a [`WorkflowUpdateHandle`](https://python.temporal.io/temporalio.client.WorkflowUpdateHandle.html), and then use `await update_handle.result()` to retrieve the result from the Update.
+
+These calls return once the requested Update wait stage has been reached, or when the request times out.
+
+You will need to provide a [`WithStartWorkflowOperation`](https://python.temporal.io/temporalio.client.WithStartWorkflowOperation.html) to define the Workflow that will be started if necessary, and its arguments.
+You must specify a [WorkflowIdConflictPolicy](/workflows#workflow-id-conflict-policy) when creating the `WithStartWorkflowOperation`.
+Note that a `WithStartWorkflowOperation` can only be used once.
+
+Here's an example taken from the [lazy_initialization](https://github.com/temporalio/samples-python/blob/main/message_passing/update_with_start/lazy_initialization/starter.py) sample:
+
+```python
+start_op = WithStartWorkflowOperation(
+    ShoppingCartWorkflow.run,
+    id=cart_id,
+    id_conflict_policy=common.WorkflowIDConflictPolicy.USE_EXISTING,
+    task_queue="my-task-queue",
+)
+try:
+    price = Decimal(
+        await temporal_client.execute_update_with_start_workflow(
+            ShoppingCartWorkflow.add_item,
+            ShoppingCartItem(sku=item_id, quantity=quantity),
+            start_workflow_operation=start_op,
+        )
+    )
+except WorkflowUpdateFailedError:
+    price = None
+
+workflow_handle = await start_op.workflow_handle()
+
+return price, workflow_handle
+```
+
+
+
 :::info SEND MESSAGES WITHOUT TYPE SAFETY
 
 In real-world development, sometimes you may be unable to import Workflow Definition method signatures.

docs/develop/typescript/message-passing.mdx

@@ -358,6 +358,50 @@ To obtain an Update handle, you can:
 - Use [`WorkflowHandle.startUpdate`](https://typescript.temporal.io/api/interfaces/client.WorkflowHandle/#startUpdate) to start an Update and return the handle, as shown in the preceding example.
 - Use [`getUpdateHandle`](https://typescript.temporal.io/api/interfaces/client.WorkflowHandle/#getupdatehandle) to fetch a handle for an in-progress Update using the Update ID.
 
+#### Update-With-Start {#update-with-start}
+
+:::tip Stability
+
+In [Public Preview](/evaluate/development-production-features/release-stages#public-preview) in Temporal Cloud.
+
+Minimum Temporal Server version [Temporal Server version 1.26](https://github.com/temporalio/temporal/releases/tag/v1.26.0)
+
+:::
+
+[Update-with-Start](/encyclopedia/workflow-message-passing#update-with-start) lets you
+[send an Update](/develop/typescript/message-passing#send-update-from-client) that checks whether an already-running Workflow with that ID exists:
+
+- If the Workflow exists, the Update is processed.
+- If the Workflow does not exist, a new Workflow Execution is started with the given ID, and the Update is processed immediately after.
+
+Use [`executeUpdateWithStart`](https://typescript.temporal.io/api/classes/client.WorkflowClient#executeUpdateWithStart) to start an Update and wait for the result in one go.
+
+Alternatively, use [`startUpdateWithStart`](https://typescript.temporal.io/api/classes/client.WorkflowClient#startUpdateWithStart) to start an Update and receive a [`WorkflowUpdateHandle`](https://typescript.temporal.io/api/interfaces/client.WorkflowUpdateHandle), and then use `await updateHandle.result()` to retrieve the result from the Update.
+
+These calls return once the requested Update wait stage has been reached, or when the request times out.
+
+You will need to provide a [`WithStartWorkflowOperation`](https://typescript.temporal.io/api/classes/client.WithStartWorkflowOperation) to define the Workflow that will be started if necessary, and its arguments.
+You must specify a [WorkflowIdConflictPolicy](/workflows#workflow-id-conflict-policy) when creating the `WithStartWorkflowOperation`.
+Note that a `WithStartWorkflowOperation` can only be used once.
+
+Here's an example taken from the [early-return](https://github.com/temporalio/samples-typescript/blob/main/early-return/src/start-test-workflow.ts) sample:
+
+```typescript
+const startWorkflowOperation = WithStartWorkflowOperation.create(transactionWorkflow, {
+  workflowId,
+  args: [transactionID],
+  taskQueue: 'early-return',
+  workflowIdConflictPolicy: 'FAIL',
+});
+
+const earlyConfirmation = await client.workflow.executeUpdateWithStart(getTransactionConfirmation, {
+  startWorkflowOperation,
+});
+const wfHandle = await startWorkflowOperation.workflowHandle();
+const finalReport = await wfHandle.result();
+```
+
+
 :::info SEND MESSAGES WITHOUT TYPE SAFETY
 
 In real-world development, sometimes you may be unable to import message type objects defined by `defineQuery`, `defineSignal`, or `defineUpdate`.

docs/encyclopedia/application-message-passing.mdx

@@ -187,32 +187,35 @@ Minimum Temporal Server version [Temporal Server version 1.26](https://github.co
 
 - Available in [Go SDK](https://pkg.go.dev/go.temporal.io/[email protected]/client#Client.UpdateWithStartWorkflow) since [v1.31.0](https://github.com/temporalio/sdk-go/releases/tag/v1.31.0)
 - Available in [Java SDK](https://www.javadoc.io/doc/io.temporal/temporal-sdk/1.27.0/io/temporal/client/WorkflowStub.html#startUpdateWithStart(io.temporal.client.UpdateOptions,java.lang.Object%5B%5D,java.lang.Object%5B%5D)) since [v1.27.0](https://github.com/temporalio/sdk-java/releases/tag/v1.27.0)
+- Available in [Python SDK](/develop/python/message-passing#send-update-from-client) since [v1.9.0](https://github.com/temporalio/sdk-python/releases/tag/1.9.0)
+- Available in [TypeScript SDK](https://typescript.temporal.io/api/interfaces/client.WorkflowHandle#executeupdate) since [v1.11.6](https://github.com/temporalio/sdk-typescript/releases/tag/v1.11.6)
+- Available in [PHP SDK](https://php.temporal.io/classes/Temporal-Client-WorkflowClient.html#method_updateWithStart) since [v2.11.4](https://github.com/temporalio/sdk-php/releases/tag/v2.11.4)
+
 
 :::
 
 Update-With-Start sends an Update that checks whether an already-running Workflow with that ID exists.
-If it does, the Update is processed.
-If not, it starts a new Workflow Execution with the supplied ID.
-When starting a new Workflow, it immediately processes the Update.
+If it does, the Update is processed normally.
+If not, it starts a new Workflow Execution with the supplied ID, and immediately processes the Update.
 
 Update-With-Start is great for latency-sensitive use cases:
 
 - **Lazy Initialization** -
   Instead of making separate Start Workflow and Update Workflow calls, Update-With-Start allows you to send them together in a single roundtrip.
-  For example, a shopping cart can be modelled using Update-With-Start.
-Updates let you add and remove items from the cart.
+  For example, a shopping cart can be modeled using Update-With-Start.
+  Updates let you add and remove items from the cart.
   Update-With-Start lets the customer start shopping, whether the cart already exists or they've just started shopping.
-  It ensures the cart, modeled by a Workflow Execution, is created before applying any Update that changes the state of items within the cart.
+  It ensures the cart, modeled by a Workflow Execution, exists before applying any Update that changes the state of items within the cart.
 - **Early Return** -
-  Using Update-With-Start can begin a new Workflow Execution and synchronously receiving a response while the Workflow Execution continues to run to completion.
+  Using Update-With-Start you can begin a new Workflow Execution and synchronously receive a response, while the Workflow Execution continues to run to completion.
   For example, you might model a payment process using Update-With-Start.
-  Whether the payment completes or rolls back, you can send the payment validation results back to the client synchronously, while attempting the transaction asynchronously.
+  This allows you to send the payment validation results back to the client synchronously, while the transaction Workflow continues in the background.
 
 :::caution
 
 Unlike Signal-with-Start - Update-With-Start is *not* atomic.
-If the Update can't be delivered, for example, say that there's no running Worker available, a new Workflow Execution will still start.
-The SDKs will retry the Update-With-Start request but there is no guarantee that it will succeed.
+If the Update can't be delivered, for example, because there's no running Worker available, a new Workflow Execution will still start.
+The SDKs will retry the Update-With-Start request, but there is no guarantee that the Update will succeed.
 
 :::