diff --git a/docs/develop/python/message-passing.mdx b/docs/develop/python/message-passing.mdx index 390d9c124c..ad5bfe4bb7 100644 --- a/docs/develop/python/message-passing.mdx +++ b/docs/develop/python/message-passing.mdx @@ -182,165 +182,11 @@ Notice that: Non-dynamic methods can only have positional arguments. -**How to customize names** - -You can have a name parameter to customize the Signal's name, otherwise it defaults to the name of the Signal method. - -
- - View the source code - - in the context of the rest of the application code. -
- -```python -from temporalio import workflow -# ... - @workflow.signal - async def submit_greeting(self, name: str) -> None: - await self._pending_greetings.put(name) - - @workflow.signal - def exit(self) -> None: -# ... - @workflow.signal(name="Custom Signal Name") - async def custom_signal(self, name: str) -> None: - await self._pending_greetings.put(name) -``` - -### Handle Signal {#handle-signal} - -**How to handle a Signal using the Python SDK.** - -Workflows listen for Signals by the Signal's name. - -Signal handlers are functions defined in the Workflow that listen for incoming Signals of a given type. -These handlers define how a Workflow should react when it receives a specific type of Signal. - -To send a Signal to the Workflow, use the [signal](https://python.temporal.io/temporalio.client.WorkflowHandle.html#signal) method from the [WorkflowHandle](https://python.temporal.io/temporalio.client.WorkflowHandle.html) class. - -
- - View the source code in the context of the rest of the application code. - - -
- -```python -from temporalio.client import Client -# ... -# ... - await handle.signal(GreetingWorkflow.submit_greeting, "User 1") -``` - -### Send a Signal from a Temporal Client {#send-signal-from-client} - -**How to send a Signal from a Temporal Client using the Python SDK.** - -When a Signal is sent successfully from the Temporal Client, the [WorkflowExecutionSignaled](/references/events#workflowexecutionsignaled) Event appears in the Event History of the Workflow that receives the Signal. - -To send a Signal from the Client, use the [signal()](https://python.temporal.io/temporalio.client.WorkflowHandle.html#signal) function on the Workflow handle. - -To get the Workflow handle, you can use any of the following options. - -- Use the [get_workflow_handle()](https://python.temporal.io/temporalio.client.Client.html#get_workflow_handle) method. -- Use the [get_workflow_handle_for()](https://python.temporal.io/temporalio.client.Client.html#get_workflow_handle_for) method to get a type-safe Workflow handle by its Workflow Id. -- Use the [start_workflow()](https://python.temporal.io/temporalio.client.Client.html#start_workflow) to start a Workflow and return its handle. - -
- - View the source code - {' '} - in the context of the rest of the application code. -
- -```python -from temporalio.client import Client -# ... -# ... - client = await Client.connect("localhost:7233") - handle = await client.start_workflow( - GreetingWorkflow.run, - id="your-greeting-workflow", - task_queue="signal-tq", - ) - await handle.signal(GreetingWorkflow.submit_greeting, "User 1") -``` - -### Send a Signal from a Workflow {#send-signal-from-workflow} - -**How to send a Signal from a Workflow using the Python SDK.** - -A Workflow can send a Signal to another Workflow, in which case it's called an _External Signal_. - -When an External Signal is sent: - -- A [SignalExternalWorkflowExecutionInitiated](/references/events#signalexternalworkflowexecutioninitiated) Event appears in the sender's Event History. -- A [WorkflowExecutionSignaled](/references/events#workflowexecutionsignaled) Event appears in the recipient's Event History. - -Use [`get_external_workflow_handle_for`](https://python.temporal.io/temporalio.workflow.html#get_external_workflow_handle_for) to get a typed Workflow handle to an existing Workflow by its identifier. -Use [`get_external_workflow_handle`](https://python.temporal.io/temporalio.workflow.html#get_external_workflow_handle) when you don't know the type of the other Workflow. - -:::note - -The Workflow Type passed is only for type annotations and not for validation. - -::: - -
- - View the source code in the context of the rest of the application code. - {' '} - -
- -```python -# ... -@workflow.defn -class WorkflowB: - @workflow.run - async def run(self) -> None: - handle = workflow.get_external_workflow_handle_for(WorkflowA.run, "workflow-a") - await handle.signal(WorkflowA.your_signal, "signal argument") -``` - -### Signal-With-Start {#signal-with-start} - -**How to send a Signal-With-Start using the Python SDK.** - -Signal-With-Start is used from the Client. -It takes a Workflow Id, Workflow arguments, a Signal name, and Signal arguments. - -If there's a Workflow running with the given Workflow Id, it will be signaled. If there isn't, a new Workflow will be started and immediately signaled. - -To send a Signal-With-Start in Python, use the [`start_workflow()`](https://python.temporal.io/temporalio.client.Client.html#start_workflow) method and pass the `start_signal` argument with the name of your Signal. - -
- - View the source code in the context of the rest of the application code. - {' '} - -
- -```python -from temporalio.client import Client -# ... -# ... -async def main(): - client = await Client.connect("localhost:7233") - await client.start_workflow( - GreetingWorkflow.run, - id="your-signal-with-start-workflow", - task_queue="signal-tq", - start_signal="submit_greeting", - start_signal_args=["User Signal with Start"], - ) -``` -## Developing with Updates {#updates} +## Updates {#updates} An [Update](/encyclopedia/workflow-message-passing#sending-updates) is a trackable request sent synchronously to a running Workflow Execution that can change the state and control the flow of a Workflow Execution, and return a result. The sender of the request must wait until the update is at least accepted or rejected by a Worker, and will often opt to wait further to receive the value returned by the Update handler, or an exception indicating what went wrong. Update handlers can do arbitrarily long-running async operations (like signal handlers, and the main workflow method).