Temporal Python SDK Mastery
Introduction to Temporal and Python SDK
What is Temporal?
Imagine you're managing a complex project, like building a house. You have a blueprint (the overall plan) and a list of specific tasks: pour the foundation, frame the walls, install plumbing. You need to make sure these tasks happen in the right order, and if something goes wrong—say, a shipment of windows is delayed—you need to handle it without forgetting where you were.
Temporal is like an expert project manager for your software. It's a platform that helps you orchestrate complex processes, ensuring they run reliably from start to finish. Instead of just executing code, Temporal runs workflows—durable, long-running processes that can survive server crashes, network outages, or other failures.
This means you can write code for a process that might take minutes, days, or even months, and trust that Temporal will keep track of its state and make sure it completes correctly. It turns complex, failure-prone distributed systems logic into straightforward, readable code.
Core Concepts
Temporal is built on two fundamental concepts: Workflows and Activities. Understanding how they work together is key to using the platform effectively.
Workflows orchestrate the business logic. They define the what and when.
Activities perform the actual work. They handle the how.
A Workflow is a function that contains the logic of your process. Think of it as the blueprint for our house-building project. It lays out the sequence of steps: first the foundation, then the framing, and so on. Critically, Workflow code must be deterministic. This means it must produce the same output every time it's given the same input, without relying on external systems or random chance. This determinism is what allows Temporal to safely re-run your workflow's history to restore its state after a crash.
An Activity is a function that performs a single, well-defined task. These are the real-world actions: calling an external API, querying a database, or sending an email. Unlike Workflows, Activities can and do interact with the outside world. This is where you put your non-deterministic code. Temporal manages executing these activities, and it can automatically retry them if they fail, which is a huge benefit for reliability.
The Temporal Service
So, if your code defines the Workflows and Activities, what keeps track of everything? That's the job of the Temporal Service (also called a Temporal Cluster).
The Temporal Service is the heart of the platform. It's a separate process that you run, either on your own servers or using Temporal's cloud offering. It acts as the ultimate source of truth, persisting the state of every running workflow. It doesn't run your code, but it orchestrates it.
When a workflow needs to run an activity, it sends a command to the Temporal Service. The service then schedules that activity to be picked up and executed by a Worker—a process you run that hosts your workflow and activity code. When the activity is done, the Worker reports the result back to the service, which then informs the workflow so it can proceed to the next step.
This separation is powerful. The service handles the durability, state management, timers, and retries. Your workers simply execute the business logic, making your application code much cleaner and more focused.
The Python SDK
To build applications with Temporal, you use a Software Development Kit (SDK) for your preferred programming language. The Temporal Python SDK lets you write your Workflows and Activities in Python, using familiar syntax like async and await.
The SDK provides the necessary building blocks to define your logic and communicate with the Temporal Service. It handles the complex background tasks, like translating your Python code into commands the service understands and ensuring your workflow code remains deterministic.
# This is a conceptual example
# Don't worry about the exact syntax yet!
from temporalio import workflow
# Define an activity interface
@workflow.activity
async def send_email(address: str, message: str) -> None:
...
# Define a workflow
@workflow.defn
class MyWorkflow:
@workflow.run
async def run(self, email_address: str) -> str:
# Execute an activity
await workflow.execute_activity(
send_email,
args=["user@example.com", "Welcome!"],
start_to_close_timeout_seconds=10
)
return "Workflow Complete"
With the SDK, you can write what looks like a simple, sequential program, but it's actually a durable, fault-tolerant process. The SDK, in partnership with the Temporal Service, takes care of pausing the workflow, waiting for activities to complete, and resuming execution when results are ready, even if that takes days.
This guide shows you how to get up and running with Agent Development Kit (ADK) for Python.
Now that you understand the basic concepts, let's get ready to test your knowledge before moving on to the hands-on parts.
What is the primary role of a Temporal Workflow?
An Activity in Temporal is the appropriate place to put which of the following?
You now have a solid foundation in what Temporal is, its core components, and how the Python SDK enables you to build reliable applications. Next, we'll dive into setting up your environment and writing your first workflow.