[sdk/python] Add an invoke_async function

[justinvp]

This commit adds a new pulumi.runtime.invoke_async function that allows calling invokes asynchronously. The initial intended use for this is inside the Kubernetes Python SDK's yaml.ConfigFile, yaml.ConfigGroup, helm, kustomize, etc. components to avoid stalls in resource registrations which severely limits parallelism.

I'd love to add some kind of benchmark, perhaps along the lines of the repro in #15462, but we can add that as a fast-follow.

Part of #15462 and #15591

After this is merged and released, we can ship an updated version of the Kubernetes Python SDK that makes use of it.

[pulumi-bot]

Changelog

[uncommitted] (2024-03-05)

Features

• [sdk/python] Add support for asynchronous invokes via a new invoke_async function
  #15602

[pgavlin]

this is probably the right signature, but it is a little odd that this isn't returning an InvokeResult. returning an InvokeResult would allow callees of invoke to transition to invoke_async by just changing the function name and adding await.

[justinvp]

Ah, I had added some comments to the PR before I tagged you, but I guess I never clicked "submit" on those. One of the comments touched on this. Went ahead and submitted those.

In any case, yeah, I went back and forth on this. It doesn't strictly need to be InvokeResult -- our other SDKs like Node don't do this, they just return Promise<T>. And originally the Python SDK didn't until we reworked the previous async invokes to be synchronous.

[justinvp]

One other thing... I don't really expect much use of this directly by users. This is a pretty advanced use case. The vast majority of users are going to be using generated provider SDK invokes. So not sure we need to optimize for avoiding having to remove a .value when transitioning. I almost lean towards the "right" signature in this case.

[pgavlin]

Sounds good to me 👍

[justinvp]

Rather than invoke_internal, I think it's reasonable to go ahead and expose this in the core SDK as invoke_async. Curious if folks feel strongly otherwise. Initially it'll only be used by those hand-authored Kubernetes components, but we may want to use it for async invoke variants of generated provider SDKs in the future.

[justinvp]

Of course, this doesn't need to be an async function that does this await. It could be:

def invoke_async(
    tok: str,
    props: "Inputs",
    opts: Optional[InvokeOptions] = None,
    typ: Optional[type] = None,
) -> Coroutine[Any, Any, Any]:
    return _invoke(tok, props, opts, typ, run_async=True)

It just somehow feels cleaner as the async func, as then I don't have to explicitly specify Coroutine[Any, Any, Any] as the return type hint.

[justinvp]

It's kind of annoying to have these overloads, but it does make the return type hinting better.

• When run_async=False it returns InvokeResult.
• When run_async=True it returns Coroutine[Any, Any, Any] (basically Awaitable[Any])

If I don't do this, then I'd either have to ignore the type check on the return wait_for_fut() or do something else to make the type checker happy.

[justinvp]

Rather than wrapping the result in InvokeResult, I'm proposing we return the result directly for the async case.