From 4fae81f86c3b78e03ea5417859f70e74d72e27fc Mon Sep 17 00:00:00 2001 From: per1234 Date: Thu, 19 Jun 2025 08:17:21 -0700 Subject: [PATCH] Disable Poetry "package mode" The project Python package dependencies are managed using the Poetry tool. By default, Poetry is configured in "package mode", which is intended for use with projects that are a Python package. When Poetry is used in a project like this that is a standalone script, this configuration is inappropriate and has the following effects: * `poetry install` command installs the project as a Python package in addition to the dependencies. * `name`, `version`, `description`, and `authors` fields of the pyproject.toml file are required. Installing the project as a package is completely inappropriate if the project is not a package, and may cause the command to fail with a cryptic error. This can be avoided by passing the `--no-root` flag to the `install` command, but that increases the usage complexity and chance for user error. Although metadata fields under the `tool.poetry` section of the pyproject.toml configuration file are important for a package, in a non-package project there are better ways to provide that information. Since Git tags are used for versioning, the presence of a `version` field is especially harmful since it means duplication of information and extra work for the project maintainer (and likelihood the metadata will not be kept updated). This "package mode" can be disabled via the pyproject.toml configuration file, which causes Poetry to operate purely in the sole capacity in which it is used by the templates: to manage dependencies. --- pyproject.toml | 5 +--- workflow-templates/assets/poetry/README.md | 26 +++++++++++++++++++ .../assets/poetry/pyproject.toml | 11 ++++++++ workflow-templates/check-mkdocs-task.md | 2 ++ workflow-templates/check-python-task.md | 18 +++---------- workflow-templates/check-yaml-task.md | 18 +++---------- workflow-templates/deploy-mkdocs-poetry.md | 18 +++---------- .../deploy-mkdocs-versioned-poetry.md | 2 +- workflow-templates/spell-check-task.md | 2 +- .../test-go-integration-task.md | 18 +++---------- workflow-templates/test-python-poetry-task.md | 18 +++---------- 11 files changed, 62 insertions(+), 76 deletions(-) create mode 100644 workflow-templates/assets/poetry/README.md create mode 100644 workflow-templates/assets/poetry/pyproject.toml diff --git a/pyproject.toml b/pyproject.toml index 94fed57b..375a4882 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,10 +2,7 @@ line-length = 120 [tool.poetry] -name = "tooling-project-assets" -version = "0.0.0" -description = "" -authors = ["Arduino "] +package-mode = false [tool.poetry.dependencies] python = "~3.9" diff --git a/workflow-templates/assets/poetry/README.md b/workflow-templates/assets/poetry/README.md new file mode 100644 index 00000000..d280df89 --- /dev/null +++ b/workflow-templates/assets/poetry/README.md @@ -0,0 +1,26 @@ +# Poetry Assets + +Python package dependencies are managed using the [**Poetry**](https://python-poetry.org/) tool. + +In addition to direct dependencies used by project Python code, **Poetry** is also used to manage Python package-based tools that are used for development and maintenance operations in the project. + +## Installation + +### Assets + +Install [`pyproject.toml`](pyproject.toml) to the root of the project repository. + +## Configuration + +### If the project is not a Python package + +No configuration is needed. + +### If the project is a Python package + +1. Delete the following line from the `pyproject.toml` file: + ```toml + package-mode = false + ``` +1. Define the package metadata under the `tool.poetry` section of the `pyproject.toml` file:
+ https://python-poetry.org/docs/pyproject#the-toolpoetry-section diff --git a/workflow-templates/assets/poetry/pyproject.toml b/workflow-templates/assets/poetry/pyproject.toml new file mode 100644 index 00000000..89f285dc --- /dev/null +++ b/workflow-templates/assets/poetry/pyproject.toml @@ -0,0 +1,11 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/poetry/pyproject.toml + +[build-system] +requires = ["poetry-core>=1.0.0"] +build-backend = "poetry.core.masonry.api" + +[tool.poetry] +package-mode = false + +[tool.poetry.dependencies] +python = "^3.9" diff --git a/workflow-templates/check-mkdocs-task.md b/workflow-templates/check-mkdocs-task.md index 5d8527b9..60cb699f 100644 --- a/workflow-templates/check-mkdocs-task.md +++ b/workflow-templates/check-mkdocs-task.md @@ -12,6 +12,8 @@ Install the [`check-mkdocs-task.yml`](check-mkdocs-task.yml) GitHub Actions work ### Assets +- [`pyproject.toml`](assets/poetry/pyproject.toml) - [**Poetry**](https://python-poetry.org/) configuration. + - Install to: repository root (unless a `pyproject.toml` file is already present). - [`Taskfile.yml`](assets/check-mkdocs-task/Taskfile.yml) - Build task. - Install to: repository root (or merge into the existing `Taskfile.yml`). - [`Taskfile.yml`](assets/poetry-task/Taskfile.yml) - Installation task. diff --git a/workflow-templates/check-python-task.md b/workflow-templates/check-python-task.md index eebbb34c..52193807 100644 --- a/workflow-templates/check-python-task.md +++ b/workflow-templates/check-python-task.md @@ -14,6 +14,8 @@ Install the [`check-python-task.yml`](check-python-task.yml) GitHub Actions work - [`.flake8`](assets/check-python/.flake8) - flake8 configuration file. - Install to: repository root +- [`pyproject.toml`](assets/poetry/pyproject.toml) - [**Poetry**](https://python-poetry.org/) configuration. + - Install to: repository root (unless a `pyproject.toml` file is already present). - [`Taskfile.yml`](assets/check-python-task/Taskfile.yml) - Python linting and formatting tasks. - Install to: repository root (or merge into the existing `Taskfile.yml`). - [`Taskfile.yml`](assets/poetry-task/Taskfile.yml) - Installation task. @@ -23,25 +25,13 @@ The code style defined in `pyproject.toml` and `.flake8` is the official standar ### Dependencies -The tool dependencies of this workflow are managed by [Poetry](https://python-poetry.org/). - -Install Poetry by following these instructions:
-https://python-poetry.org/docs/#installation - -If your project does not already use Poetry, you can initialize the [`pyproject.toml`](https://python-poetry.org/docs/pyproject/) file using these commands: - -``` -poetry init --python="^3.9" --dev-dependency="black@^25.1.0" --dev-dependency="flake8@^7.2.0" --dev-dependency="pep8-naming@^0.15.1" -poetry install -``` - -If already using Poetry, add the tool using this command: +Add the tool dependencies using this command: ``` poetry add --dev "black@^25.1.0" "flake8@^7.2.0" "pep8-naming@^0.15.1" ``` -Commit the resulting `pyproject.toml` and `poetry.lock` files. +Commit the resulting changes to the `pyproject.toml` and `poetry.lock` files. ### Configuration diff --git a/workflow-templates/check-yaml-task.md b/workflow-templates/check-yaml-task.md index 29e80847..7ca5aecb 100644 --- a/workflow-templates/check-yaml-task.md +++ b/workflow-templates/check-yaml-task.md @@ -16,6 +16,8 @@ Install the [check-yaml-task.yml](check-yaml-task.yml) GitHub Actions workflow t - [`.yamllint.yml`](assets/check-yaml/.yamllint.yml) - `yamllint` configuration file. - Install to: repository root +- [`pyproject.toml`](assets/poetry/pyproject.toml) - [**Poetry**](https://python-poetry.org/) configuration. + - Install to: repository root (unless a `pyproject.toml` file is already present). - [`Taskfile.yml`](assets/check-yaml-task/Taskfile.yml) - Linting task. - Install to: repository root (or merge into the existing `Taskfile.yml`). - [`Taskfile.yml`](assets/poetry-task/Taskfile.yml) - Installation task. @@ -25,25 +27,13 @@ The code style defined in this file is the official standardized style to be use ### Dependencies -The `yamllint` tool dependency is managed by [Poetry](https://python-poetry.org/). - -Install Poetry by following these instructions:
-https://python-poetry.org/docs/#installation - -If your project does not already use Poetry, you can initialize the [`pyproject.toml`](https://python-poetry.org/docs/pyproject/) file using these commands: - -``` -poetry init --python="^3.9" --dev-dependency="yamllint@^1.37.1" -poetry install -``` - -If already using Poetry, add the tool using this command: +Add the tool dependency using this command: ``` poetry add --dev "yamllint@^1.37.1" ``` -Commit the resulting `pyproject.toml` and `poetry.lock` files. +Commit the resulting changes to the `pyproject.toml` and `poetry.lock` files. ### Configuration diff --git a/workflow-templates/deploy-mkdocs-poetry.md b/workflow-templates/deploy-mkdocs-poetry.md index 715abb87..d46f8aee 100644 --- a/workflow-templates/deploy-mkdocs-poetry.md +++ b/workflow-templates/deploy-mkdocs-poetry.md @@ -12,6 +12,8 @@ Install the [`deploy-mkdocs-poetry.yml`](deploy-mkdocs-poetry.yml) GitHub Action ### Assets +- [`pyproject.toml`](assets/poetry/pyproject.toml) - [**Poetry**](https://python-poetry.org/) configuration. + - Install to: repository root (unless a `pyproject.toml` file is already present). - [`Taskfile.yml`](assets/poetry-task/Taskfile.yml) - Python package dependency management tasks. - Install to: repository root (or merge into the existing `Taskfile.yml`). - [`mkdocs.yml`](assets/mkdocs/mkdocs.yml) - base MkDocs configuration file. @@ -21,25 +23,13 @@ Install the [`deploy-mkdocs-poetry.yml`](deploy-mkdocs-poetry.yml) GitHub Action ### Dependencies -The website build dependencies are managed by [Poetry](https://python-poetry.org/). - -Install Poetry by following these instructions:
-https://python-poetry.org/docs/#installation - -If your project does not already use Poetry, you can initialize the [`pyproject.toml`](https://python-poetry.org/docs/pyproject/) file using these commands: - -``` -poetry init --python="^3.9" --dev-dependency="mkdocs@^1.3.0" --dev-dependency="mkdocs-material@^8.2.11" --dev-dependency="mdx_truly_sane_lists@^1.2" -poetry install -``` - -If already using Poetry, add the tool using this command: +Add the tool dependencies using this command: ``` poetry add --dev "mkdocs@^1.3.0" "mkdocs-material@^8.2.11" "mdx_truly_sane_lists@^1.2" ``` -Commit the resulting `pyproject.toml` and `poetry.lock` files. +Commit the resulting changes to the `pyproject.toml` and `poetry.lock` files. ### Configuration diff --git a/workflow-templates/deploy-mkdocs-versioned-poetry.md b/workflow-templates/deploy-mkdocs-versioned-poetry.md index 833f8cb3..d343d5cd 100644 --- a/workflow-templates/deploy-mkdocs-versioned-poetry.md +++ b/workflow-templates/deploy-mkdocs-versioned-poetry.md @@ -35,7 +35,7 @@ See the ["Deploy Website" workflow (MkDocs, Poetry) documentation](deploy-mkdocs ``` poetry add --dev "gitpython@^3.1.44" "mike@^1.1.2" ``` -1. Commit the resulting `pyproject.toml` and `poetry.lock` files. +1. Commit the resulting changes to the `pyproject.toml` and `poetry.lock` files. ### Configuration diff --git a/workflow-templates/spell-check-task.md b/workflow-templates/spell-check-task.md index 9cd8b306..706003fd 100644 --- a/workflow-templates/spell-check-task.md +++ b/workflow-templates/spell-check-task.md @@ -39,7 +39,7 @@ If already using Poetry, add the tool using this command: poetry add --dev "codespell@^2.4.0" ``` -Commit the resulting `pyproject.toml` and `poetry.lock` files. +Commit the resulting changes to the `pyproject.toml` and `poetry.lock` files. ### Configuration diff --git a/workflow-templates/test-go-integration-task.md b/workflow-templates/test-go-integration-task.md index f8103f69..6385270b 100644 --- a/workflow-templates/test-go-integration-task.md +++ b/workflow-templates/test-go-integration-task.md @@ -12,6 +12,8 @@ Install the [`test-go-integration-task.yml`](test-go-integration-task.yml) GitHu ## Assets +- [`pyproject.toml`](assets/poetry/pyproject.toml) - [**Poetry**](https://python-poetry.org/) configuration. + - Install to: repository root (unless a `pyproject.toml` file is already present). - [`Taskfile.yml`](assets/test-go-integration-task/Taskfile.yml) - Test runner task. - Install to: repository root (or merge into the existing `Taskfile.yml`). - [`Taskfile.yml`](assets/go-task/Taskfile.yml) - Build task. @@ -27,25 +29,13 @@ Install the [`test-go-integration-task.yml`](test-go-integration-task.yml) GitHu ### Dependencies -The Python dependencies are managed by [Poetry](https://python-poetry.org/). - -Install Poetry by following these instructions:
-https://python-poetry.org/docs/#installation - -If your project does not already use Poetry, you can initialize the [`pyproject.toml`](https://python-poetry.org/docs/pyproject/) file using these commands: - -``` -poetry init --python="^3.9" --dev-dependency="pytest@^8.4.1" --dev-dependency="invoke@^1.7.0" -poetry install -``` - -If already using Poetry, add the tool using this command: +Add the tool dependencies using this command: ``` poetry add --dev "pytest@^8.4.1" "invoke@^1.7.0" ``` -Commit the resulting `pyproject.toml` and `poetry.lock` files. +Commit the resulting changes to the `pyproject.toml` and `poetry.lock` files. ### Configuration diff --git a/workflow-templates/test-python-poetry-task.md b/workflow-templates/test-python-poetry-task.md index 5a5c97ba..0d0e2a1a 100644 --- a/workflow-templates/test-python-poetry-task.md +++ b/workflow-templates/test-python-poetry-task.md @@ -12,6 +12,8 @@ Install the [`test-python-poetry-task.yml`](test-python-poetry-task.yml) GitHub ### Assets +- [`pyproject.toml`](assets/poetry/pyproject.toml) - [**Poetry**](https://python-poetry.org/) configuration. + - Install to: repository root (unless a `pyproject.toml` file is already present). - [`Taskfile.yml`](assets/test-python-poetry-task/Taskfile.yml) - Test runner task. - Install to: repository root (or merge into the existing `Taskfile.yml`). - [`Taskfile.yml`](assets/poetry-task/Taskfile.yml) - Installation task. @@ -25,25 +27,13 @@ Install the [`test-python-poetry-task.yml`](test-python-poetry-task.yml) GitHub ### Dependencies -The Python dependencies are managed by [Poetry](https://python-poetry.org/). - -Install Poetry by following these instructions:
-https://python-poetry.org/docs/#installation - -If your project does not already use Poetry, you can initialize the [`pyproject.toml`](https://python-poetry.org/docs/pyproject/) file using these commands: - -``` -poetry init --python="^3.9" --dev-dependency="pytest@^8.4.1" -poetry install -``` - -If already using Poetry, add the tool using this command: +Add the tool dependency using this command: ``` poetry add --dev "pytest@^8.4.1" ``` -Commit the resulting `pyproject.toml` and `poetry.lock` files. +Commit the resulting changes to the `pyproject.toml` and `poetry.lock` files. ### Readme badge