From c2850456e39002761d31b275d7a61d1d7b7cfc6b Mon Sep 17 00:00:00 2001 From: Julien Poissonnier Date: Fri, 28 Jun 2024 14:52:42 +0200 Subject: [PATCH 1/4] Add Python Poetry documentation We now have native `poetry` support to manage virtual enviroments and dependencies. Ref: https://github.com/pulumi/pulumi/issues/15937 --- content/docs/languages-sdks/python/_index.md | 86 ++++++++++++-------- layouts/shortcodes/install-python.html | 3 +- 2 files changed, 55 insertions(+), 34 deletions(-) diff --git a/content/docs/languages-sdks/python/_index.md b/content/docs/languages-sdks/python/_index.md index 2bbf912eee33..03a92dbc093d 100644 --- a/content/docs/languages-sdks/python/_index.md +++ b/content/docs/languages-sdks/python/_index.md @@ -26,7 +26,7 @@ The Pulumi programming model defines the core concepts you will use when creatin Pulumi. [Concepts](/docs/intro/concepts) describes these concepts with examples available in Python. These concepts are made available to you in the Pulumi SDK. -The Pulumi SDK is available to Python developers as a Pip package distributed on PyPI. To learn more, +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/). 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. @@ -44,53 +44,38 @@ asynchronous code within Python Pulumi programs. ### Virtual Environments -It is not required, but we recommend using a virtual environment to isolate the dependencies of your projects and ensure reproducibility between machines. +It is not required, but we recommend using a [virtual environment](https://docs.python.org/3/tutorial/venv.html) to isolate the dependencies of your projects and ensure reproducibility between machines. -As of Pulumi 2.4.0, new Python projects created with `pulumi new` will have a virtual environment created in a `venv` directory with required dependencies from `requirements.txt` installed in it, and Pulumi will automatically use this virtual environment when running the program. +When creating a new Python project with `pulumi new`, you are offered the choice between `pip` (default) and `poetry` to manage your dependencies. If you choose `pip`, Pulumi will create a virtual environment in a `venv` directory with required dependencies from `requirements.txt` installed in it. If you choose `poetry`, Pulumi will create a `pyproject.toml` file and run poetry to create a virtual environment in its [default location](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment). Pulumi will automatically use this virtual environment when running the program. -This behavior is controlled by the following `virtualenv` `runtime` option in `Pulumi.yaml`: +This behavior is controlled by the `toolchain` and `virtualenv` `runtime` options in `Pulumi.yaml`. + +Set the `toolchain` option to `pip`, along with the `virtualenv` option to use `pip`: ```yaml runtime: name: python options: + toolchain: pip virtualenv: venv ``` `virtualenv` is the path to a virtual environment to use. -Existing Python projects can opt-in to using the built-in virtual environment support by setting the `virtualenv` option. To manually create a virtual environment and install dependencies, run the following commands in your project directory: - -{{< chooser os "macos,windows,linux" >}} - -{{% choosable os macos %}} +Set the `toolchain` option to `poetry` to use `poetry`: -```bash -$ python3 -m venv venv -$ venv/bin/pip install -r requirements.txt -``` - -{{% /choosable %}} - -{{% choosable os linux %}} - -```bash -$ python3 -m venv venv -$ venv/bin/pip install -r requirements.txt +```yaml +runtime: + name: python + options: + toolchain: poetry ``` -{{% /choosable %}} - -{{% choosable os windows %}} - -```bat -> python -m venv venv -> venv\Scripts\pip install -r requirements.txt -``` +To further configure `poetry`, you can provide a [`poetry.toml` configuration file](https://python-poetry.org/docs/configuration/#local-configuration) in the project directory. -{{% /choosable %}} +Existing Python projects that do not use a virtual environment can opt-in to using the built-in virtual environment support by setting the above options. After updating the options, run `pulumi install` to create the virtual environment and install dependencies. -{{< /chooser >}} +#### Self managed virtual environments If you prefer to manage the virtual environment on your own (for example, using a tool like [Pipenv](https://github.com/pypa/pipenv)), you can delete the local `venv` directory and unset the `virtualenv` option in `Pulumi.yaml`: @@ -119,7 +104,9 @@ When set, Pulumi will invoke the type checker before running your program. This There are many [Pulumi Python packages](/registry) available. -To install a new dependency in the virtual environment, add an entry to `requirements.txt`, and run the following in your project directory: +#### Pip + +To install a new dependency in the virtual environment when using `pip`, add an entry to `requirements.txt`, and run the following in your project directory: {{< chooser os "macos,windows,linux" >}} @@ -149,9 +136,42 @@ $ venv/bin/pip install -r requirements.txt {{< /chooser >}} +#### Poetry + +To add a new dependency when using `poetry`, run the `poetry add` command in your project directory: + +{{< chooser os "macos,windows,linux" >}} + +{{% choosable os macos %}} + +```bash +$ poetry add ${PACKAGE_NAME} +``` + +{{% /choosable %}} + +{{% choosable os linux %}} + +```bash +$ poetry add ${PACKAGE_NAME} +``` + +{{% /choosable %}} + +{{% choosable os windows %}} + +```bat +> poetry add ${PACKAGE_NAME} + +``` + +{{% /choosable %}} + +{{< /chooser >}} + ### Dev Versions -Pulumi SDKs also publish pre-release versions, that include all the latest changes from the main development branch. If you would like to install them, you can use the `--pre` flag to do so. For example `pip install --pre -r requirements.txt`. +Pulumi SDKs also publish pre-release versions, that include all the latest changes from the main development branch. If you would like to install them, you can use the `--pre` flag with `pip install` to do so. For example `pip install --pre -r requirements.txt`. When using `poetry`, add the `--allow-prereleases` flag to the `poetry add` command. For example `poetry add --allow-prereleases ${PACKAGE_NAME}`. ## Package Documentation diff --git a/layouts/shortcodes/install-python.html b/layouts/shortcodes/install-python.html index ecccaebac99b..40d16f86460c 100644 --- a/layouts/shortcodes/install-python.html +++ b/layouts/shortcodes/install-python.html @@ -11,12 +11,13 @@

- pip is required to install dependencies. If you installed Python from source, with an installer from + pip or poetry are required to install dependencies. If you installed Python from source, with an installer from python.org, or via Homebrew you should already have pip. If Python is installed using your OS package manager, you may have to install pip separately, see Installing pip/setuptools/wheel with Linux Package Managers. For example, on Debian/Ubuntu you must run sudo apt install python3-venv python3-pip. + To install poetry follow the installation instructions.

From cc2ee8e0cdfa52e1ba5cd7d87a409dda16414aad Mon Sep 17 00:00:00 2001 From: Julien P Date: Mon, 1 Jul 2024 12:22:53 +0200 Subject: [PATCH 2/4] Update content/docs/languages-sdks/python/_index.md Co-authored-by: Christian Nunciato --- content/docs/languages-sdks/python/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/languages-sdks/python/_index.md b/content/docs/languages-sdks/python/_index.md index 03a92dbc093d..ad5e15871544 100644 --- a/content/docs/languages-sdks/python/_index.md +++ b/content/docs/languages-sdks/python/_index.md @@ -50,7 +50,7 @@ When creating a new Python project with `pulumi new`, you are offered the choice This behavior is controlled by the `toolchain` and `virtualenv` `runtime` options in `Pulumi.yaml`. -Set the `toolchain` option to `pip`, along with the `virtualenv` option to use `pip`: +To use pip, set the `toolchain` option to `pip`, along with the `virtualenv` option: ```yaml runtime: From 3de0ca5991ccb2808e27dd45c78383613278fb60 Mon Sep 17 00:00:00 2001 From: Julien P Date: Mon, 1 Jul 2024 12:24:04 +0200 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Christian Nunciato --- content/docs/languages-sdks/python/_index.md | 11 ++++++++--- layouts/shortcodes/install-python.html | 2 +- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/content/docs/languages-sdks/python/_index.md b/content/docs/languages-sdks/python/_index.md index ad5e15871544..864ede24a2a5 100644 --- a/content/docs/languages-sdks/python/_index.md +++ b/content/docs/languages-sdks/python/_index.md @@ -46,7 +46,7 @@ asynchronous code within Python Pulumi programs. It is not required, but we recommend using a [virtual environment](https://docs.python.org/3/tutorial/venv.html) to isolate the dependencies of your projects and ensure reproducibility between machines. -When creating a new Python project with `pulumi new`, you are offered the choice between `pip` (default) and `poetry` to manage your dependencies. If you choose `pip`, Pulumi will create a virtual environment in a `venv` directory with required dependencies from `requirements.txt` installed in it. If you choose `poetry`, Pulumi will create a `pyproject.toml` file and run poetry to create a virtual environment in its [default location](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment). Pulumi will automatically use this virtual environment when running the program. +When creating a new Python project with `pulumi new`, you are offered the choice between pip (default) and `poetry` to manage your dependencies. If you choose `pip`, Pulumi will create a virtual environment in a `venv` directory with required dependencies from `requirements.txt` installed in it. If you choose `poetry`, Pulumi will create a `pyproject.toml` file and run Poetry to create a virtual environment in its [default location](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment). Pulumi will automatically use this virtual environment when running the program. This behavior is controlled by the `toolchain` and `virtualenv` `runtime` options in `Pulumi.yaml`. @@ -62,7 +62,7 @@ runtime: `virtualenv` is the path to a virtual environment to use. -Set the `toolchain` option to `poetry` to use `poetry`: +To use Poetry, set the `toolchain` option to `poetry`: ```yaml runtime: @@ -171,7 +171,12 @@ $ poetry add ${PACKAGE_NAME} ### Dev Versions -Pulumi SDKs also publish pre-release versions, that include all the latest changes from the main development branch. If you would like to install them, you can use the `--pre` flag with `pip install` to do so. For example `pip install --pre -r requirements.txt`. When using `poetry`, add the `--allow-prereleases` flag to the `poetry add` command. For example `poetry add --allow-prereleases ${PACKAGE_NAME}`. +Pulumi SDKs also publish pre-release versions that include all the latest changes from the main development branch. If you would like to install a pre-release version, you can use the `--pre` flag with `pip` or the `--allow-prereleaases` flag with `poetry`. For example: + +```bash +pip install --pre -r requirements.txt +poetry add --allow-prereleases ${PACKAGE_NAME} +``` ## Package Documentation diff --git a/layouts/shortcodes/install-python.html b/layouts/shortcodes/install-python.html index 40d16f86460c..88e5b196ddcb 100644 --- a/layouts/shortcodes/install-python.html +++ b/layouts/shortcodes/install-python.html @@ -11,7 +11,7 @@

- pip or poetry are required to install dependencies. If you installed Python from source, with an installer from + Either pip or poetry is required to install dependencies. If you installed Python from source, with an installer from python.org, or via Homebrew you should already have pip. If Python is installed using your OS package manager, you may have to install pip separately, see From 7fa66f05a7b81d5071e4075a5a9da1e03b5fd692 Mon Sep 17 00:00:00 2001 From: Julien Poissonnier Date: Mon, 1 Jul 2024 12:31:09 +0200 Subject: [PATCH 4/4] lint --- content/docs/languages-sdks/python/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/languages-sdks/python/_index.md b/content/docs/languages-sdks/python/_index.md index 864ede24a2a5..e8d65e3590f4 100644 --- a/content/docs/languages-sdks/python/_index.md +++ b/content/docs/languages-sdks/python/_index.md @@ -50,7 +50,7 @@ When creating a new Python project with `pulumi new`, you are offered the choice This behavior is controlled by the `toolchain` and `virtualenv` `runtime` options in `Pulumi.yaml`. -To use pip, set the `toolchain` option to `pip`, along with the `virtualenv` option: +To use pip, set the `toolchain` option to `pip`, along with the `virtualenv` option: ```yaml runtime: