From 990f22a6b6ee2f2293447515d805b91c8e9efb86 Mon Sep 17 00:00:00 2001 From: Julien Poissonnier Date: Tue, 23 Jul 2024 11:42:11 +0200 Subject: [PATCH] Document Python Args and ArgsDict types Document how in Python inputs can either be argument classes or dictionary literals. Ref https://github.com/pulumi/registry/issues/4936 --- content/docs/languages-sdks/python/_index.md | 30 ++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/content/docs/languages-sdks/python/_index.md b/content/docs/languages-sdks/python/_index.md index 59dbc0052db3..053c8fef459b 100644 --- a/content/docs/languages-sdks/python/_index.md +++ b/content/docs/languages-sdks/python/_index.md @@ -29,8 +29,38 @@ with examples available in Python. These concepts are made available to you in t The Pulumi SDK is available to Python developers as a package distributed on PyPI. To learn more, [refer to the Pulumi SDK Reference Guide](/docs/reference/pkg/python/pulumi/). +### Inputs and Outputs + The Pulumi programming model includes a core concept of `Input` and `Output` values, which are used to track how outputs of one resource flow in as inputs to another resource. This concept is important to understand when getting started with Python and Pulumi, and the [Inputs and Outputs](/docs/concepts/inputs-outputs/) documentation is recommended to get a feel for how to work with this core part of Pulumi in common cases. +In Python, inputs that are objects, that is inputs that group multiple values together, can be reprented either as classes or as dictionary literals. The types for the argument classes have the suffix `Args`, whereas the types for the dictionaries have the suffix `ArgsDict`. Both types take the same arguments, but the dictionary types are often more concise. + +{{% notes type="info" %}} +The types with the suffix `ArgsDict` for dictionary literals were introduced in July 2024. You can still use dictionary literals with providers that have not been updated yet with this change, but you will not benefit from the type checking that the new types provide. +{{% /notes %}} + +This example shows two ways to create an `s3.Bucket` resource in Python, once using a dictionary literal and once using a class: + +```python +import pulumi_aws as aws + +bucket = aws.s3.Bucket( + "my-bucket-with-dictionary-literals", + website={ + "error_document": "error.html", + "index_document": "index.html", + }, +) + +bucket = aws.s3.Bucket( + "my-bucket-with-args", + website=aws.s3.BucketWebsiteArgs( + error_document="error.html", + index_document="index.html", + ), +) +``` + ### Blocking and Asynchronous Code A Python Pulumi program is single threaded and the Pulumi runtime creates an