Package: village-temporal
Temporal Python SDKTemporalis a distributed, scalable, durable, and highly available orchestration engine used to
execute asynchronous long-running business logic in a scalable and resilient way."Temporal Python SDK" is the framework for authoring workflows and activities using the Python programming language.Also see:Code SamplesAPI DocumentationApplication Development GuideIn addition to features common across all Temporal SDKs, the Python SDK also has the following interesting features:Type SafeThis library uses the latest typing and MyPy support with generics to ensure all calls can be typed. For example,
starting a workflow with anintparameter when it accepts astrparameter would cause MyPy to fail.Different Activity TypesThe activity worker has been developed to work withasync def, threaded, and multiprocess activities. Whileasync defactivities are the easiest and recommended, care has been taken to make heartbeating and cancellation also
work across threads/processes.CustomasyncioEvent LoopThe workflow implementation basically turnsasync deffunctions into workflows backed by a distributed, fault-tolerant
event loop. This means task management, sleep, cancellation, etc have all been developed to seamlessly integrate withasyncioconcepts.⚠️ UNDER DEVELOPMENTThe Python SDK is under development. There are no compatibility guarantees at this time.Quick StartInstallationInstall thetemporaliopackage fromPyPI.These steps can be followed to use with a virtual environment andpip:Create a virtual environmentUpdatepip-python -m pip install -U pipNeeded because older versions ofpipmay not pick the right wheelInstall Temporal SDK -python -m pip install temporalioThe SDK is now ready for use. To build from source, see "Building" near the end of this documentation.NOTE: This README is for the current branch and not necessarily what's released onPyPI.Implementing a WorkflowCreate the following script atrun_worker.py:importasynciofromdatetimeimportdatetime,timedeltafromtemporalioimportworkflow,activityfromtemporalio.clientimportClientfromtemporalio.workerimportWorker@activity.defnasyncdefsay_hello(name:str)->str:returnf"Hello,{name}!"@workflow.defnclassSayHello:@workflow.runasyncdefrun(self,name:str)->str:returnawaitworkflow.execute_activity(say_hello,name,schedule_to_close_timeout=timedelta(seconds=5))asyncdefmain():# Create client connected to server at the given addressclient=awaitClient.connect("localhost:7233")# Run the workerworker=Worker(client,task_queue="my-task-queue",workflows=[SayHello],activities=[say_hello])awaitworker.run()if__name__=="__main__":asyncio.run(main())Assuming you have aTemporal server running on localhost, this
will run the worker:python run_worker.pyRunning a WorkflowCreate the following script atrun_workflow.py:importasynciofromtemporalio.clientimportClient# Import the workflow from the previous codefromrun_workerimportSayHelloasyncdefmain():# Create client connected to server at the given addressclient=awaitClient.connect("localhost:7233")# Execute a workflowresult=awaitclient.execute_workflow(SayHello.run,"my name",id="my-workflow-id",task_queue="my-task-queue")print(f"Result:{result}")if__name__=="__main__":asyncio.run(main())Assuming you haverun_worker.pyrunning from before, this will run the workflow:python run_workflow.pyThe output will be:Result: Hello, my-name!UsageClientA client can be created and used to start a workflow like so:fromtemporalio.clientimportClientasyncdefmain():# Create client connected to server at the given address and namespaceclient=awaitClient.connect("localhost:7233",namespace="my-namespace")# Start a workflowhandle=awaitclient.start_workflow(MyWorkflow.run,"some arg",id="my-workflow-id",task_queue="my-task-queue")# Wait for resultresult=awaithandle.result()print(f"Result:{result}")Some things to note about the above code:AClientdoes not have an explicit "close"To enable TLS, thetlsargument toconnectcan be set toTrueor aTLSConfigobjectA single positional argument can be passed tostart_workflow. If there are multiple arguments, only the
non-type-safe form ofstart_workflowcan be used (i.e. the one accepting a string workflow name) and it must be in
theargskeyword argument.Thehandlerepresents the workflow that was started and can be used for more than just getting the resultSince we are just getting the handle and waiting on the result, we could have calledclient.execute_workflowwhich
does the same thingClients can have many more options not shown here (e.g. data converters and interceptors)A string can be used instead of the method reference to call a workflow by name (e.g. if defined in another language)Clients also provide a shallow copy of their config for use in making slightly different clients backed by the same
connection. For instance, given theclientabove, this is how to have a client in another namespace:config=client.config()config["namespace"]="my-other-namespace"other_ns_client=Client(**config)Data ConversionData converters are used to convert raw Temporal payloads to/from actual Python types. A custom data converter of typetemporalio.converter.DataConvertercan be set via thedata_converterclient parameter. Data converters are a
combination of payload converters and payload codecs. The former converts Python values to/from serialized bytes, and
the latter converts bytes to bytes (e.g. for compression or encryption).The default data converter supports converting multiple types including:Nonebytesgoogle.protobuf.message.Message- As JSON when encoding, but has ability to decode binary proto from other languagesAnything that can be converted to JSON including:Anything thatjson.dumpsupports nativelydataclassesIterables including ones JSON dump may not support by default, e.g.setAny class with adict()method and a staticparse_obj()method, e.g.Pydantic modelsIntEnumbased enumeratesFor converting from JSON, the workflow/activity type hint is taken into account to convert to the proper type. Care has
been taken to support all common typings includingOptional,Union, all forms of iterables and mappings,NewType,
etc in addition to the regular JSON values mentioned before.Users are strongly encouraged to use a singledataclassfor parameter and return types so fields with defaults can be
easily added without breaking compatibility.WorkersWorkers host workflows and/or activities. Here's how to run a worker:importasyncioimportloggingfromtemporalio.clientimportClientfromtemporalio.workerimportWorker# Import your own workflows and activitiesfrommy_workflow_packageimportMyWorkflow,my_activityasyncdefrun_worker(stop_event:asyncio.Event):# Create client connected to server at the given addressclient=awaitClient.connect("localhost:7233",namespace="my-namespace")# Run the worker until the event is setworker=Worker(client,task_queue="my-task-queue",workflows=[MyWorkflow],activities=[my_activity])asyncwithworker:awaitstop_event.wait()Some things to note about the above code:This creates/uses the same client that is used for starting workflowsWhile this example accepts a stop event and usesasync with,run()andshutdown()may be used insteadWorkers can have many more options not shown here (e.g. data converters and interceptors)WorkflowsDefinitionWorkflows are defined as classes decorated with@workflow.defn. The method invoked for the workflow is decorated with@workflow.run. Methods for signals and queries are decorated with@workflow.signaland@workflow.queryrespectively. Here's an example of a workflow:importasynciofromdataclassesimportdataclassfromdatetimeimporttimedeltafromtemporalioimportactivity,workflowfromtemporalio.clientimportClientfromtemporalio.workerimportWorker@dataclassclassGreetingInfo:salutation:str="Hello"name:str="<unknown>"@workflow.defnclassGreetingWorkflow:def__init__()->None:self._current_greeting="<unset>"self._greeting_info=GreetingInfo()self._greeting_info_update=asyncio.Event()self._complete=asyncio.Event()@workflow.runasyncdefrun(self,name:str)->str:self._greeting_info.name=namewhileTrue:# Store greetingself._current_greeting=awaitworkflow.execute_activity(create_greeting_activity,self._greeting_info,start_to_close_timeout=timedelta(seconds=5),)workflow.logger.debug("Greeting set to%s",self._current_greeting)# Wait for salutation update or complete signal (this can be# cancelled)awaitasyncio.wait([self._greeting_info_update.wait(),self._complete.wait()],return_when=asyncio.FIRST_COMPLETED,)ifself._complete.is_set():returnself._current_greetingself._greeting_info_update.clear()@workflow.signalasyncdefupdate_salutation(self,salutation:str)->None:self._greeting_info.salutation=salutationself._greeting_info_update.set()@workflow.signalasyncdefcomplete_with_greeting(self)->None:self._complete.set()@workflow.queryasyncdefcurrent_greeting(self)->str:returnself._current_greeting@activity.defnasyncdefcreate_greeting_activity(info:GreetingInfo)->str:returnf"{info.salutation},{info.name}!"Some things to note about the above code:This workflow continually updates the queryable current greeting when signalled and can complete with the greeting on
a different signalWorkflows are always classes and must have a single@workflow.runwhich is anasync deffunctionWorkflow code must be deterministic. This means no threading, no randomness, no external calls to processes, no
network IO, and no global state mutation. All code must run in the implicitasyncioevent loop and be deterministic.@activity.defnis explained in a later section. For normal simple string concatenation, this would just be done in
the workflow. The activity is for demonstration purposes only.workflow.execute_activity(create_greeting_activity, ...is actually a typed signature, and MyPy will fail if theself._greeting_infoparameter is not aGreetingInfoHere are the decorators that can be applied:@workflow.defn- Defines a workflow classMust be defined on the class given to the worker (ignored if present on a base class)Can have anameparam to customize the workflow name, otherwise it defaults to the unqualified class name@workflow.run- Defines the primary workflow run methodMust be defined on the same class as@workflow.defn, not a base class (but canalsobe defined on the same
method of a base class)Exactly one method name must have this decorator, no more or lessMust be defined on anasync defmethodThe method's arguments are the workflow's argumentsThe first parameter must beself, followed by positional arguments. Best practice is to only take a single
argument that is an object/dataclass of fields that can be added to as needed.@workflow.signal- Defines a method as a signalCan be defined on anasyncor non-asyncfunction at any hierarchy depth, but if decorated method is overridden,
the override must also be decoratedThe method's arguments are the signal's argumentsCan have anameparam to customize the signal name, otherwise it defaults to the unqualified method nameCan havedynamic=Truewhich means all otherwise unhandled signals fall through to this. If present, cannot havenameargument, and method parameters must beself, a string signal name, and a*argsvarargs param.Non-dynamic method can only have positional arguments. Best practice is to only take a single argument that is an
object/dataclass of fields that can be added to as needed.Return value is ignored@workflow.query- Defines a method as a queryAll the same constraints as@workflow.signalbut should return a valueTemporal queries should never mutate anything in the workflowRunningTo start a locally-defined workflow from a client, you can simply reference its method like so:fromtemporalio.clientimportClientfrommy_workflow_packageimportGreetingWorkflowasyncdefcreate_greeting(client:Client)->str:# Start the workflowhandle=awaitclient.start_workflow(GreetingWorkflow.run,"my name",id="my-workflow-id",task_queue="my-task-queue")# Change the salutationawaithandle.signal(GreetingWorkflow.update_salutation,"Aloha")# Tell it to completeawaithandle.signal(GreetingWorkflow.complete_with_greeting)# Wait and return resultreturnawaithandle.result()Some things to note about the above code:This uses theGreetingWorkflowfrom the previous sectionThe result of calling this function is"Aloha, my name!"idandtask_queueare required for running a workflowclient.start_workflowis typed, so MyPy would fail if"my name"were something besides a stringhandle.signalis typed, so MyPy would fail if"Aloha"were something besides a string or if we provided a
parameter to the parameterlesscomplete_with_greetinghandle.resultis typed to the workflow itself, so MyPy would fail if we said thiscreate_greetingreturned
something besides a stringInvoking ActivitiesActivities are started with non-asyncworkflow.start_activity()which accepts either an activity function reference
or a string name.A single argument to the activity is positional. Multiple arguments are not supported in the type-safe form of
start/execute activity and must be supplied via theargskeyword argument.Activity options are set as keyword arguments after the activity arguments. At least one ofstart_to_close_timeoutorschedule_to_close_timeoutmust be provided.The result is an activity handle which is anasyncio.Taskand supports basic task featuresAn asyncworkflow.execute_activity()helper is provided which takes the same arguments asworkflow.start_activity()andawaits on the result. This should be used in most cases unless advanced task
capabilities are needed.Local activities work very similarly except the functions areworkflow.start_local_activity()andworkflow.execute_local_activity()Activities can be methods of a class. Invokers should useworkflow.start_activity_method(),workflow.execute_activity_method(),workflow.start_local_activity_method(), andworkflow.execute_local_activity_method()instead.Activities can callable classes (i.e. that define__call__). Invokers should useworkflow.start_activity_class(),workflow.execute_activity_class(),workflow.start_local_activity_class(), andworkflow.execute_local_activity_class()instead.Invoking Child WorkflowsChild workflows are started with asyncworkflow.start_child_workflow()which accepts either a workflow run method
reference or a string name. The arguments to the workflow are positional.A single argument to the child workflow is positional. Multiple arguments are not supported in the type-safe form of
start/execute child workflow and must be supplied via theargskeyword argument.Child workflow options are set as keyword arguments after the arguments. At leastidmust be provided.Theawaitof the start does not complete until the start has been accepted by the serverThe result is a child workflow handle which is anasyncio.Taskand supports basic task features. The handle also has
some child info and supports signalling the child workflowAn asyncworkflow.execute_child_workflow()helper is provided which takes the same arguments asworkflow.start_child_workflow()andawaits on the result. This should be used in most cases unless advanced task
capabilities are needed.TimersA timer is represented by normalasyncio.sleep()Timers are also implicitly started on anyasynciocalls with timeouts (e.g.asyncio.wait_for)Timers are Temporal server timers, not local ones, so sub-second resolution rarely has valueConditionsworkflow.wait_conditionis an async function that doesn't return until a provided callback returns trueAtimeoutcan optionally be provided which will throw aasyncio.TimeoutErrorif reached (internally backed byasyncio.wait_forwhich uses a timer)Asyncio and CancellationWorkflows are backed by a customasyncioevent loop. This means many
of the commonasynciocalls work as normal. Some asyncio features are disabled such as:Thread related calls such asto_thread(),run_coroutine_threadsafe(),loop.run_in_executor(), etcCalls that alter the event loop such asloop.close(),loop.stop(),loop.run_forever(),loop.set_task_factory(), etcCalls that use a specific time such asloop.call_at()Calls that use anything external such as networking, subprocesses, disk IO, etcCancellation is done the same way asasyncio. Specifically, a task can be requested to be cancelled but does not
necessarily have to respect that cancellation immediately. This also means thatasyncio.shield()can be used to
protect against cancellation. The following tasks, when cancelled, perform a Temporal cancellation:Activities - when the task executing an activity is cancelled, a cancellation request is sent to the activityChild workflows - when the task starting or executing a child workflow is cancelled, a cancellation request is sent to
cancel the child workflowTimers - when the task executing a timer is cancelled (whether started via sleep or timeout), the timer is cancelledWhen the workflow itself is requested to cancel,Task.cancelis called on the main workflow task. Therefore,asyncio.CancelledErrorcan be caught in order to handle the cancel gracefully.Workflows followasynciocancellation rules exactly which can cause confusion among Python developers. Cancelling a
task doesn't always cancel the thing it created. For example, giventask = asyncio.create_task(workflow.start_child_workflow(..., callingtask.canceldoes not cancel the child
workflow, it only cancels the starting of it, which has no effect if it has already started. However, cancelling the
result ofhandle = await workflow.start_child_workflow(...ortask = asyncio.create_task(workflow.execute_child_workflow(...doescancel the child workflow.Also, due to Temporal rules, a cancellation request is a state not an event. Therefore, repeated cancellation requests
are not delivered, only the first. If the workflow chooses swallow a cancellation, it cannot be requested again.Workflow UtilitiesWhile running in a workflow, in addition to features documented elsewhere, the following items are available from thetemporalio.workflowpackage:continue_as_new()- Async function to stop the workflow immediately and continue as newinfo()- Returns information about the current workflowlogger- A logger for use in a workflow (properly skips logging on replay)now()- Returns the "current time" from the workflow's perspectiveExceptionsWorkflows can raise exceptions to fail the workflowUsingtemporalio.exceptions.ApplicationError, exceptions can be marked as non-retryable or include detailsExternal Workflowsworkflow.get_external_workflow_handle()inside a workflow returns a handle to interact with another workflowworkflow.get_external_workflow_handle_for()can be used instead for a type safe handleawait handle.signal()can be called on the handle to signal the external workflowawait handle.cancel()can be called on the handle to send a cancel to the external workflowTestingWorkflow testing can be done in an integration-test fashion against a real server, however it is hard to simulate
timeouts and other long time-based code. Using the time-skipping workflow test environment can help there.The time-skippingtemporalio.testing.WorkflowEnvironmentcan be created via the static asyncstart_time_skipping().
This internally downloads the Temporal time-skipping test server to a temporary directory if it doesn't already exist,
then starts the test server which has special APIs for skipping time.Automatic Time SkippingAnytime a workflow result is waited on, the time-skipping server automatically advances to the next event it can. To
manually advance time before waiting on the result of a workflow, theWorkflowEnvironment.sleepmethod can be used.Here's a simple example of a workflow that sleeps for 24 hours:importasynciofromtemporalioimportworkflow@workflow.defnclassWaitADayWorkflow:@workflow.runasyncdefrun(self)->str:awaitasyncio.sleep(24*60*60)return"all done"An integration test of this workflow would be way too slow. However the time-skipping server automatically skips to the
next event when we wait on the result. Here's a test for that workflow:fromtemporalio.testingimportWorkflowEnvironmentfromtemporalio.workerimportWorkerasyncdeftest_wait_a_day_workflow():asyncwithawaitWorkflowEnvironment.start_time_skipping()asenv:asyncwithWorker(env.client,task_queue="tq1",workflows=[WaitADayWorkflow]):assert"all done"==awaitenv.client.execute_workflow(WaitADayWorkflow.run,id="wf1",task_queue="tq1")That test will run almost instantly. This is because by callingexecute_workflowon our client, we have asked the
environment to automatically skip time as much as it can (basically until the end of the workflow or until an activity
is run).To disable automatic time-skipping while waiting for a workflow result, run code inside awith env.auto_time_skipping_disabled():block.Manual Time SkippingUntil a workflow is waited on, all time skipping in the time-skipping environment is done manually viaWorkflowEnvironment.sleep.Here's workflow that waits for a signal or times out:importasynciofromtemporalioimportworkflow@workflow.defnclassSignalWorkflow:def__init__(self)->None:self.signal_received=False@workflow.runasyncdefrun(self)->str:# Wait for signal or timeout in 45 secondstry:awaitworkflow.wait_condition(lambda:self.signal_received,timeout=45)return"got signal"exceptasyncio.TimeoutError:return"got timeout"@workflow.signaldefsome_signal(self)->None:self.signal_received=TrueTo test a normal signal, you might:fromtemporalio.testingimportWorkflowEnvironmentfromtemporalio.workerimportWorkerasyncdeftest_signal_workflow():asyncwithawaitWorkflowEnvironment.start_time_skipping()asenv:asyncwithWorker(env.client,task_queue="tq1",workflows=[SignalWorkflow]):# Start workflow, send signal, check resulthandle=awaitenv.client.start_workflow(SignalWorkflow.run,id="wf1",task_queue="tq1")awaithandle.signal(SignalWorkflow.some_signal)assert"got signal"==awaithandle.result()But how would you test the timeout part? Like so:fromtemporalio.testingimportWorkflowEnvironmentfromtemporalio.workerimportWorkerasyncdeftest_signal_workflow_timeout():asyncwithawaitWorkflowEnvironment.start_time_skipping()asenv:asyncwithWorker(env.client,task_queue="tq1",workflows=[SignalWorkflow]):# Start workflow, advance time past timeout, check resulthandle=awaitenv.client.start_workflow(SignalWorkflow.run,id="wf1",task_queue="tq1")awaitenv.sleep(50)assert"got timeout"==awaithandle.result()Also, the current time of the workflow environment can be obtained via the asyncWorkflowEnvironment.get_current_timemethod.Mocking ActivitiesActivities are just functions decorated with@activity.defn. Simply write different ones and pass those to the worker
to have different activities called during the test.ActivitiesDefinitionActivities are decorated with@activity.defnlike so:fromtemporalioimportactivity@activity.defnasyncdefsay_hello_activity(name:str)->str:returnf"Hello,{name}!"Some things to note about activity definitions:Thesay_hello_activityisasyncwhich is the recommended activity type (see "Types of Activities" below)A custom name for the activity can be set with a decorator argument, e.g.@activity.defn(name="my activity")Long running activities should regularly heartbeat and handle cancellationActivities can only have positional arguments. Best practice is to only take a single argument that is an
object/dataclass of fields that can be added to as needed.Activities can be defined on methods instead of top-level functions. This allows the instance to carry state that an
activity may need (e.g. a DB connection). The instance method should be what is registered with the worker.Activities can also be defined on callable classes (i.e. classes with__call__). An instance of the class should be
what is registered with the worker.Types of ActivitiesThere are 3 types of activity callables accepted and described below: asynchronous, synchronous multithreaded, and
synchronous multiprocess/other. Only positional parameters are allowed in activity callables.Asynchronous ActivitiesAsynchronous activities, i.e. functions usingasync def, are the recommended activity type. When using asynchronous
activities no special worker parameters are needed.Cancellation for asynchronous activities is done viaasyncio.Task.cancel. This means thatasyncio.CancelledErrorwill be raised (and can be caught, but it is not recommended). An activity must heartbeat to
receive cancellation and there are other ways to be notified about cancellation (see "Activity Context" and
"Heartbeating and Cancellation" later).Synchronous ActivitiesSynchronous activities, i.e. functions that do not haveasync def, can be used with workers, but theactivity_executorworker parameter must be set with aconcurrent.futures.Executorinstance to use for executing the
activities.Cancellation for synchronous activities is done in the background and the activity must choose to listen for it and
react appropriately. An activity must heartbeat to receive cancellation and there are other ways to be notified about
cancellation (see "Activity Context" and "Heartbeating and Cancellation" later).Note, all calls from an activity to functions in thetemporalio.activitypackage are powered bycontextvars. Therefore, new threads startinginsideof
activities mustcopy_context()and then.run()manually to ensuretemporalio.activitycalls likeheartbeatstill
function in the new threads.Synchronous Multithreaded ActivitiesIfactivity_executoris set to an instance ofconcurrent.futures.ThreadPoolExecutorthen the synchronous activities
are considered multithreaded activities. Besidesactivity_executor, no other worker parameters are required for
synchronous multithreaded activities.Synchronous Multiprocess/Other ActivitiesIfactivity_executoris set to an instance ofconcurrent.futures.Executorthat isnotconcurrent.futures.ThreadPoolExecutor, then the synchronous activities are considered multiprocess/other activities.These require special primitives for heartbeating and cancellation. Theshared_state_managerworker parameter must be
set to an instance oftemporalio.worker.SharedStateManager. The most common implementation can be created by passing amultiprocessing.managers.SyncManager(i.e. result ofmultiprocessing.managers.Manager()) totemporalio.worker.SharedStateManager.create_from_multiprocessing().Also, all of these activity functions must be"picklable".Activity ContextDuring activity execution, an implicit activity context is set as acontext variable. The context variable itself is not visible, but
calls in thetemporalio.activitypackage make use of it. Specifically:in_activity()- Whether an activity context is presentinfo()- Returns the immutable info of the currently running activityheartbeat(*details)- Record a heartbeatis_cancelled()- Whether a cancellation has been requested on this activitywait_for_cancelled()-asynccall to wait for cancellation requestwait_for_cancelled_sync(timeout)- Synchronous blocking call to wait for cancellation requestis_worker_shutdown()- Whether the worker has started graceful shutdownwait_for_worker_shutdown()-asynccall to wait for start of graceful worker shutdownwait_for_worker_shutdown_sync(timeout)- Synchronous blocking call to wait for start of graceful worker shutdownraise_complete_async()- Raise an error that this activity will be completed asynchronously (i.e. after return of
the activity function in a separate client call)With the exception ofin_activity(), if any of the functions are called outside of an activity context, an error
occurs. Synchronous activities cannot call any of theasyncfunctions.Heartbeating and CancellationIn order for an activity to be notified of cancellation requests, they must invoketemporalio.activity.heartbeat().
It is strongly recommended that all but the fastest executing activities call this function regularly. "Types of
Activities" has specifics on cancellation for asynchronous and synchronous activities.In addition to obtaining cancellation information, heartbeats also support detail data that is persisted on the server
for retrieval during activity retry. If an activity callstemporalio.activity.heartbeat(123, 456)and then fails and
is retried,temporalio.activity.info().heartbeat_detailswill return an iterable containing123and456on the
next run.Worker ShutdownAn activity can react to a worker shutdown. Usingis_worker_shutdownor one of thewait_for_worker_shutdownfunctions an activity can react to a shutdown.When thegraceful_shutdown_timeoutworker parameter is given adatetime.timedelta, on shutdown the worker will
notify activities of the graceful shutdown. Once that timeout has passed (or if wasn't set), the worker will perform
cancellation of all outstanding activities.Theshutdown()invocation will wait on all activities to complete, so if a long-running activity does not at least
respect cancellation, the shutdown may never complete.TestingUnit testing an activity or any code that could run in an activity is done via thetemporalio.testing.ActivityEnvironmentclass. Simply instantiate this and any callable + params passed torunwill
be invoked inside the activity context. The following are attributes/methods on the environment that can be used to
affect calls activity code might make to functions on thetemporalio.activitypackage.infoproperty can be set to customize what is returned fromactivity.info()on_heartbeatproperty can be set to handleactivity.heartbeat()callscancel()can be invoked to simulate a cancellation of the activityworker_shutdown()can be invoked to simulate a worker shutdown during execution of the activityWorkflow ReplayGiven a workflow's history, it can be replayed locally to check for things like non-determinism errors. For example,
assuminghistory_json_stris populated with a JSON string history either exported from the web UI or fromtctl, the
following function will replay it:fromtemporalio.workerimportReplayerasyncdefrun_replayer(history_json_str:str):replayer=Replayer(workflows=[SayHello])awaitreplayer.replay_workflow(history_json_str)This will throw an error if any non-determinism is detected.OpenTelemetry SupportOpenTelemetry support requires the optionalopentelemetrydependencies which are part of theopentelemetryextra.
When usingpip, runningpip install temporalio[opentelemetry]will install needed dependencies. Then thetemporalio.contrib.opentelemetry.TracingInterceptorcan be created and set
as an interceptor on theinterceptorsargument ofClient.connect. When set, spans will be created for all client
calls and for all activity and workflow invocations on the worker, spans will be created and properly serialized through
the server to give one proper trace for a workflow execution.DevelopmentThe Python SDK is built to work with Python 3.7 and newer. It is built usingSDK Corewhich is written in Rust.BuildingPrepareTo build the SDK from source for use as a dependency, the following prerequisites are required:Python>= 3.7Rustpoetry(e.g.python -m pip install poetry)poe(e.g.python -m pip install poethepoet)macOS note: If errors are encountered, it may be better to install Python and Rust as recommended from their websites
instead of viabrew.With the prerequisites installed, first clone the SDK repository recursively:gitclone--recursivehttps://github.com/temporalio/sdk-python.gitcdsdk-pythonUsepoetryto install the dependencies with--no-rootto not install this package (because we still need to build
it):poetryinstall--no-rootBuildNow perform the release build:This will take a while because Rust will compile the core project in release mode (seeLocal SDK development
environmentfor the quicker approach to local development).poetrybuildThe compiled wheel doesn't have the exact right tags yet for use, so run this script to fix it:poefix-wheelThewhlwheel file indist/is now ready to use.UseThe wheel can now be installed into any virtual environment.For example,create a virtual environmentsomewhere and then run the following inside the virtual environment:pipinstallwheelpipinstall/path/to/cloned/sdk-python/dist/*.whlCreate this Python file atexample.py:importasynciofromtemporalioimportworkflow,activityfromtemporalio.clientimportClientfromtemporalio.workerimportWorker@workflow.defnclassSayHello:@workflow.runasyncdefrun(self,name:str)->str:returnf"Hello,{name}!"asyncdefmain():client=awaitClient.connect("localhost:7233")asyncwithWorker(client,task_queue="my-task-queue",workflows=[SayHello]):result=awaitclient.execute_workflow(SayHello.run,"Temporal",id="my-workflow-id",task_queue="my-task-queue")print(f"Result:{result}")if__name__=="__main__":asyncio.run(main())Assuming there is alocal Temporal serverrunning, execute the
file withpython(orpython3if necessary):pythonexample.pyIt should output:Result: Hello, Temporal!Local SDK development environmentFor local development, it is often quicker to use debug builds and a local virtual environment.While not required, it often helps IDEs if we put the virtual environment.venvdirectory in the project itself. This
can be configured system-wide via:poetryconfigvirtualenvs.in-projecttrueNow perform the same steps as the "Prepare" section above by installing the prerequisites, cloning the project,
installing dependencies, and generating the protobuf code:gitclone--recursivehttps://github.com/temporalio/sdk-python.gitcdsdk-python
poetryinstall--no-rootNow compile the Rust extension in develop mode which is quicker than release mode:poebuild-developThat step can be repeated for any Rust changes made.The environment is now ready to develop in.TestingTests currently requireGoto be installed since they use an embedded Temporal server as a library.
WithGoinstalled, run the following to execute tests:poetestStyleMostlyGoogle Style Guide. Notable exceptions:We useBlackfor formatting, so that takes precedenceIn tests and example code, can import individual classes/functions to make it more readable. Can also do this for
rarely in library code for some Python common items (e.g.dataclassorpartial), but not allowed to do this for
anytemporaliopackages (excepttemporalio.types) or any classes/functions that aren't clear when unqualified.We allow relative imports for private packagesWe allow@staticmethod