[Python] TypedDict input types

[julienp]

Previous discussion https://docs.google.com/document/d/1BT4ILg-q-q-XgYRuDOBOYHdNIiICWcgpewMOhMdFcjE/edit

With pulumi/pulumi#12689 we have TypedDict based types for inputs. You could previously already pass dictionaries as inputs, but these did not have type checking, and we mostly discouraged using plain dictionaries (by defaulting to Args classes in docs and examples).

Now that these are typed, we want to promote their use, and we were considering adding them to the constructor syntax in the registry docs. The option we settled on was to show the Union[${Soemthing}Args, ${Something}ArgsDict].

To accomplish this, we can pass true for acceptMapping in GetLanguageTypeString https://github.com/pulumi/pulumi/blob/ff1f7434aa8c899f94aa2b170cf225c012c8c66c/pkg/codegen/python/doc.go#L83

The result is fairly verbose:

and also shows up in other places:

It also does not tell the user how to use these types.

I wonder if it would be better to add a conceptual explanation to the docs in the Inputs section (for example here https://www.pulumi.com/registry/packages/kubernetes/api-docs/apps/v1/deployment/#properties), and/or on the Python SDK page, that explains that you can either use an Args class or a (typed) dictionary.

[julienp]

Showing the Union really clutters up the docs, without giving useful information to the user (nowhere do we show the actual types of the union).

Instead of the clutter, we link to the python docs about inputs at the top of the section pulumi/pulumi#16763