Feature request: Call activities as decorated functions inside workflows (sugar over execute_activity)

[maver1ck]

Problem
In the Python SDK, workflows must invoke activities explicitly via workflow.execute_activity() / start_activity(). This adds boilerplate at call sites (repeating options like timeouts/retries) and surprises users who expect decorator‑marked callables to be directly invocable inside workflows.

Why it matters

• Readability/teachability: code is less declarative; @activity.defn looks like a function you can call, but you can’t.
• Ergonomics: the same options are repeated in every call site even when they’re identical.
• Consistency: other task/flow frameworks allow direct invocation of decorated tasks within flows, reducing ceremony.

Comparison with Prefect
Below are minimal examples showing how a similar pattern looks today.

Prefect (2.x):

from prefect import flow, task

@task
def fetch_article(url: str) -> str:
    ...

@flow
def pipeline(url: str):
    # Direct call (sync semantics) or .submit() for concurrency
    html = fetch_article(url)
    # html = fetch_article.submit(url)
    return html

Temporal Python today:

from datetime import timedelta
from temporalio import workflow
from temporalio import activity

@activity.defn
async def fetch_article(url: str) -> str:
    ...

@workflow.defn
class Pipeline:
    @workflow.run
    async def run(self, url: str) -> str:
        html = await workflow.execute_activity(
            fetch_article,
            url,
            start_to_close_timeout=timedelta(seconds=30),
            # plus any retry/heartbeat options at each call site
        )
        return html

This issue is to track interest in more ergonomic, decorator‑style activity invocation in Python workflows—while preserving Temporal’s determinism and activity semantics. No specific API is proposed here; the goal is to document the pain point and contrast with common expectations from Prefect‑style flows.

[cretz]

This was a very intentional decision during the design of the APIs. We did the looks-like-normal-function approach in Java and (kinda) TypeScript and have since backed off that approach.

Firstly, we don't want activity invocation to look like regular function invocation. You need to understand that you are invoking an activity and not just calling a Python function.

Secondly, you need to be able to provide options to an activity. Languages like Java and TypeScript that did the looks-like-normal-function-invocation have confusing away-from-call semantics for providing activity options.

Thirdly, there is start_activity, execute_activity, start_local_activity, and execute_local_activity (and sometime in the future maybe more for standalone activities). The activity implementation/decorator does not decide which of those to use, the caller does. And we don't want inconsistency between starting and executing or inconsistency between local and non-local.

Fourthly, we support activities as methods with calls like start_activity_method and execute_activity_method. It is very common. How would that work in this scenario?

Fifthly, we want consistency with how you start/execute workflows, which are classes not functions.

Finally, for those that do want to give up this explicitness/clarity and know exactly how they may call an activity (local or not, what options, etc), they can make this decorator/utility themselves.

Feel free to join us on #python-sdk on Slack for general discussion topics.

[maver1ck]

Hi @cretz,
Thank you for the great explanation.

start_activity vs execute_activity

Let's start with start_activity vs execute_activity
From my understanding this is simpler problem to solve.

Let's assume that we have custom decorator:

@callable_activity.defn(start_to_close_timeout=timedelta(seconds=30))
async def fetch_article(url: str) -> str:
    ...

Parameters of start/execute may be defined in decorator

Then we have two options how to use it:

1. without await which equals to start_activity

article_activity1 = fetch_article(url1)
article_activity2 = fetch_article(url2)
article1 = await article_activity1
article2 = await article_activity2

2. with await which equals to execute_activity

article = await fetch_article(url)

local vs non-local

This may be just solved using parameters in decorator

@callable_activity.defn(local=True)
async def fetch_article(url: str) -> str:
    ...

Finally, for those that do want to give up this explicitness/clarity and know exactly how they may call an activity (local or not, what options, etc), they can make this decorator/utility themselves.

Of course this is something that may be easy implemented outside of SDK (probably also for workflows).
The question is - is it valuable addition to Python SDK.

[cretz]

Then we have two options how to use it:

There are more calls than just start/execute, and there are many other reasons listed. And we may want to add more things to workflow-specific https://python.temporal.io/temporalio.workflow.ActivityHandle.html (returned from start only if you call start inside of workflows) which we would never alter the decorator's type hint to return because we want standalone activities too (which will be these same activities called from non-worfklow contexts).

This may be just solved using parameters in decorator

This is a caller choice not an implementer choice

And there are many other reasons listed for why we want activity invocation to be explicit and not hidden