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.

Author: per1234

pyproject.toml

@@ -2,10 +2,7 @@
 line-length = 120
 
 [tool.poetry]
-name = "tooling-project-assets"
-version = "0.0.0"
-description = ""
-authors = ["Arduino <[email protected]>"]
+package-mode = false
 
 [tool.poetry.dependencies]
 python = "~3.9"

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:<br />
+   https://python-poetry.org/docs/pyproject#the-toolpoetry-section

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"

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.

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:<br />
-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
 

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:<br />
-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
 

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:<br />
-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
 

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
 

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
 

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:<br />
-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
 

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:<br />
-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