diff --git a/docs/tutorials/python/geocoding-app/index.md b/docs/tutorials/python/geocoding-app/index.md index 7c24ab70..999faeb5 100644 --- a/docs/tutorials/python/geocoding-app/index.md +++ b/docs/tutorials/python/geocoding-app/index.md @@ -112,19 +112,18 @@ class GeoCode: ``` -The `GeoCode` class is decorated with `@workflow.defn`, which +You decorated the `GeoCode` class with `@workflow.defn`, which tells Temporal that the class is a Workflow. -The `async def run()` function is decorated with `@workflow.run`, which tells +You decorated the `run()` method with `@workflow.run`, which tells Temporal that this method is the Workflow's run method. As mentioned in the code comment, -the Workflow needs exactly one method -to be decorated with `@workflow.run`. +you apply this decorator to exactly one method in the Workflow. -The Activities are passed into the calls to `workflow.execute_activity(activity)`. -If the Activities need arguments, pass the arguments in after the Activity: -`workflow.execute_activity(activity, args*, ...)`, as is done in the execution of `get_lat_long`. It's +You passed the Activities into the calls to `workflow.execute_activity(activity)`. +If the Activities need arguments, pass them in after the Activity: +`workflow.execute_activity(activity, args*, ...)`, as you did in the execution of `get_lat_long()`. It's recommended to collapse the arguments into a single one using a dataclass, -which is shown here as `QueryParams` (it will be defined in the next section). +which you did here with `QueryParams`. With the skeleton in place, you can now develop the Activities. @@ -161,9 +160,8 @@ async def get_address_from_user() -> str: The `@activity.defn` decorator is what tells Temporal that this function is an Activity. -These Activities are -called in the beginning of the Workflow you made earlier. After the Workflow -calls these two, it has the user's API key and address. Next, +You call these Activities in the Workflow you made earlier. After the Workflow +calls these them, it has the user's API key and address. Next, it calls an Activity called `get_lat_long`, with an argument of type `QueryParams`. You'll implement that next. @@ -206,14 +204,14 @@ an API call that needs the user's location and API key, so you'll bundle those as a data class. That's `QueryParams`. Now that you have the Workflow and Actions, you need to run them. In -the next section, you'll begin that process by making and running a worker. +the next section, you'll begin that process by making and running a Worker. ## Create a Worker to host your Workflow and Activities -The last conceptual piece you need is a worker. The worker +The last conceptual piece you need is a Worker. The Worker is the process that connects to the Temporal Service, and listens on a certain Task Queue for any work to do. Here is how you can make -a worker factory. +a Worker factory. Make a new file called `make_worker.py` and enter the following: @@ -276,22 +274,22 @@ if __name__ == "__main__": This code connects to the Temporal Service using `Client.connect`. -You'll run this code soon, and when you do, the Temporal Service -will need to be running for this line to work (which is why it was mentioned in the -prerequisites). +For this to work, Temporal Service +needs to be running (which is why you ensured it was running in +the prerequisites). -Next, the code passes that `client` into the preceeding `make_worker` function. +Next, the code passes that `client` into the `make_worker` function you made earlier. This returns a Worker, which you use to call the `.run()` method. This is what makes the Worker run -and start listening for work on the Task Queue. You will run it now. +and start listening for work on the Task Queue. You will run it now. 1. Open a new terminal (keep the service running in a different terminal). 2. Navigate to the project directory, and run the following command (it won't output anything yet). -``` -$ python run_worker.py +```command +python run_worker.py ``` It will start listening, but it has nothing @@ -336,9 +334,9 @@ if __name__ == "__main__": In this piece, you connect to the service, then call `execute_workflow()`. The arguments are the following: -- The Workflow method that was decorated with `@workflow.defn`. +- The Workflow method that you decorated with `@workflow.defn`. - The ID for the Workflow. -- The Task Queue. This is the queue to which the Workflow (and its Activities) +- The Task Queue. This is the queue to which the Workflow and its Activities are added. You're ready to run the code. Do the following 4 steps: @@ -348,8 +346,8 @@ You're ready to run the code. Do the following 4 steps: 2. Navigate to the project directory, and run the following command: -``` -$ python run_workflow.py +```command +python run_workflow.py ``` At this point, the @@ -383,8 +381,8 @@ Now on your own, try defining a Retry Policy and applying it to the Activities.
-What are some examples of things that would be done in an Activity instead of in -the body of the Workflow? Which ones did you do in this tutorial? +What are some examples of things that Temporal recommends to do in Activities instead of in +Workflow methods? Which ones did you do in this tutorial? Activities perform anything that may be non-deterministic, may fail, or have side effects. This could be writing to