Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document Python Args and ArgsDict types #12346

Merged
merged 2 commits into from
Jul 24, 2024
Merged

Document Python Args and ArgsDict types #12346

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
990f22a
Document Python Args and ArgsDict types
julienp Jul 23, 2024
785c9f5
Apply suggestions from code review
julienp Jul 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions content/docs/languages-sdks/python/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 represented 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](/docs/concepts/how-pulumi-works/#resource-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

bucket1 = aws.s3.Bucket(
"my-bucket-with-dictionary-literals",
website={
"error_document": "error.html",
"index_document": "index.html",
},
)

bucket2 = 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
Expand Down
Loading