Merge branch 'master' of https://github.com/python-poetry/poetry into patch-1

Author: rmorshea-atom-computing

Diff for: .pre-commit-config.yaml

@@ -20,17 +20,17 @@ repos:
       - id: debug-statements
       - id: check-docstring-first
 
-  - repo: https://github.com/psf/black
-    rev: 23.7.0
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 23.9.0
     hooks:
       - id: black
 
   - repo: https://github.com/pre-commit/pre-commit
-    rev: v3.3.3
+    rev: v3.4.0
     hooks:
       - id: validate_manifest
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.286
+    rev: v0.0.287
     hooks:
     -   id: ruff

Diff for: docs/_index.md

@@ -23,18 +23,85 @@ on Linux, macOS and Windows.
 
 ## Installation
 
+{{% warning %}}
+Poetry should always be installed in a dedicated virtual environment to isolate it from the rest of your system.
+In no case, it should be installed in the environment of the project that is to be managed by Poetry.
+This ensures that Poetry's own dependencies will not be accidentally upgraded or uninstalled.
+(Each of the following installation methods ensures that Poetry is installed into an isolated environment.)
+{{% /warning %}}
+
 {{% note %}}
 If you are viewing documentation for the development branch, you may wish to install a preview or development version of Poetry.
 See the **advanced** installation instructions to use a preview or alternate version of Poetry.
 {{% /note %}}
 
-{{< tabs tabTotal="4" tabID1="installing-with-the-official-installer" tabID2="installing-with-pipx" tabID3="installing-manually" tabID4="ci-recommendations" tabName1="With the official installer" tabName2="With pipx" tabName3="Manually (advanced)" tabName4="CI recommendations">}}
+{{< tabs tabTotal="4" tabID1="installing-with-pipx" tabID2="installing-with-the-official-installer" tabID3="installing-manually" tabID4="ci-recommendations" tabName1="With pipx" tabName2="With the official installer" tabName3="Manually (advanced)" tabName4="CI recommendations">}}
+
+{{< tab tabID="installing-with-pipx" >}}
+
+[`pipx`](https://github.com/pypa/pipx) is used to install Python CLI applications globally while still isolating them in virtual environments.
+`pipx` will manage upgrades and uninstalls when used to install Poetry.
+
+{{< steps >}}
+{{< step >}}
+**Install Poetry**
+
+```bash
+pipx install poetry
+```
+{{< /step >}}
+{{< step >}}
+**Install Poetry (advanced)**
+
+`pipx` can install different versions of Poetry, using the same syntax as pip:
+
+```bash
+pipx install poetry==1.2.0
+```
+
+`pipx` can also install versions of Poetry in parallel, which allows for easy testing of alternate or prerelease
+versions. Each version is given a unique, user-specified suffix, which will be used to create a unique binary name:
+
+```bash
+pipx install [email protected] poetry==1.2.0
+[email protected] --version
+```
+
+```bash
+pipx install --suffix=@preview --pip-args=--pre poetry
+poetry@preview --version
+```
+
+Finally, `pipx` can install any valid [pip requirement spec](https://pip.pypa.io/en/stable/cli/pip_install/), which
+allows for installations of the development version from `git`, or even for local testing of pull requests:
+
+```bash
+pipx install --suffix @master git+https://github.com/python-poetry/poetry.git@master
+pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head
+```
+
+{{< /step >}}
+{{< step >}}
+**Update Poetry**
+
+```bash
+pipx upgrade poetry
+```
+{{< /step >}}
+{{< step >}}
+**Uninstall Poetry**
+
+```bash
+pipx uninstall poetry
+```
+{{< /step >}}
+{{< /steps >}}
 
+{{< /tab >}}
 {{< tab tabID="installing-with-the-official-installer" >}}
 
-We provide a custom installer that will install Poetry in a new virtual environment to isolate it
-from the rest of your system. This ensures that dependencies will not be accidentally upgraded or
-uninstalled, and allows Poetry to manage its own environment.
+We provide a custom installer that will install Poetry in a new virtual environment
+and allows Poetry to manage its own environment.
 
 {{< steps >}}
 {{< step >}}
@@ -145,6 +212,11 @@ If you see something like `Poetry (version 1.2.0)`, your install is ready to use
 
 Poetry is able to update itself when installed using the official installer.
 
+{{% warning %}}
+Especially on Windows, `self update` may be problematic
+so that a re-install with the installer should be preferred.
+{{% /warning %}}
+
 ```bash
 poetry self update
 ```
@@ -193,69 +265,6 @@ Also remove ~/.poetry/bin from your `$PATH` in your shell configuration, if it i
 {{< /step >}}
 {{< /steps >}}
 
-{{< /tab >}}
-{{< tab tabID="installing-with-pipx" >}}
-
-Using [`pipx`](https://github.com/pypa/pipx) to install Poetry is also possible and fully supported.
-
-`pipx` is used to install Python CLI applications globally while still isolating them in virtual environments.
-`pipx` will manage upgrades and uninstalls when used to install Poetry.
-
-{{< steps >}}
-{{< step >}}
-**Install Poetry**
-
-```bash
-pipx install poetry
-```
-{{< /step >}}
-{{< step >}}
-**Install Poetry (advanced)**
-
-`pipx` can be install different versions of Poetry, using the same syntax as pip:
-
-```bash
-pipx install poetry==1.2.0
-```
-
-`pipx` can also install versions of Poetry in parallel, which allows for easy testing of alternate or prerelease
-versions. Each version is given a unique, user-specified suffix, which will be used to create a unique binary name:
-
-```bash
-pipx install [email protected] poetry==1.2.0
-[email protected] --version
-```
-
-```bash
-pipx install --suffix=@preview --pip-args=--pre poetry
-poetry@preview --version
-```
-
-Finally, `pipx` can install any valid [pip requirement spec](https://pip.pypa.io/en/stable/cli/pip_install/), which
-allows for installations of the development version from `git`, or even for local testing of pull requests:
-
-```bash
-pipx install --suffix @master git+https://github.com/python-poetry/poetry.git@master
-pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head
-```
-
-{{< /step >}}
-{{< step >}}
-**Update Poetry**
-
-```bash
-pipx upgrade poetry
-```
-{{< /step >}}
-{{< step >}}
-**Uninstall Poetry**
-
-```bash
-pipx uninstall poetry
-```
-{{< /step >}}
-{{< /steps >}}
-
 {{< /tab >}}
 {{< tab tabID="installing-manually" >}}
 
@@ -280,19 +289,34 @@ To uninstall Poetry, simply delete the entire `$VENV_PATH` directory.
 Unlike development environments, where making use of the latest tools is desirable, in a CI environment reproducibility
 should be made the priority. Here are some suggestions for installing Poetry in such an environment.
 
-**Installation method**
+**Version pinning**
+
+Whatever method you use, it is highly recommended to explicitly control the version of Poetry used, so that you are able
+to upgrade after performing your own validation. Each install method has a different syntax for setting the version that
+is used in the following examples.
+
+**Using pipx**
+
+Just as `pipx` is a powerful tool for development use, it is equally useful in a CI environment
+and should be one of your top choices for use of Poetry in CI.
+
+```bash
+pipx install poetry==1.2.0
+```
+
+**Using install.python-poetry.org**
 
+{{% note %}}
 The official installer script ([install.python-poetry.org](https://install.python-poetry.org)) offers a streamlined and
 simplified installation of Poetry, sufficient for developer use or for simple pipelines. However, in a CI environment
 the other two supported installation methods (pipx and manual) should be seriously considered.
-
-**Using install.python-poetry.org**
+{{% /note %}}
 
 Downloading a copy of the installer script to a place accessible by your CI pipelines (or maintaining a copy of the
 [repository](https://github.com/python-poetry/install.python-poetry.org)) is strongly suggested, to ensure your
 pipeline's stability and to maintain control over what code is executed.
 
-By default the installer will install to a user-specific directory. In more complex pipelines that may make accessing
+By default, the installer will install to a user-specific directory. In more complex pipelines that may make accessing
 Poetry difficult (especially in cases like multi-stage container builds). It is highly suggested to make use of
 `$POETRY_HOME` when using the official installer in CI, as that way the exact paths can be controlled.
 
@@ -302,17 +326,6 @@ python3 install-poetry.py --version 1.2.0
 $POETRY_HOME/bin/poetry --version
 ```
 
-**Using pipx**
-
-Just as `pipx` is a powerful tool for development use, it is equally useful in a CI environment. It takes the same steps
-the installer does to safely install Poetry isolated from the rest of your system, but is generic and able to do this
-for any Python package, with a syntax/usage that is similar to `pip`. `pipx` should be considered equally supported in
-comparison to the official installer, and should be one of your top choices for use of Poetry in CI.
-
-```bash
-pipx install poetry==1.2.0
-```
-
 **Using pip (aka manually)**
 
 For maximum control in your CI environment, installation with `pip` is fully supported and something you should
@@ -332,21 +345,6 @@ as the target environment managed by Poetry. If Poetry and your project are inst
 is likely to upgrade or uninstall its own dependencies (causing hard-to-debug and understand errors).
 {{% /note %}}
 
-**Version pinning**
-
-Whatever method you use, it is highly recommended to explicitly control the version of Poetry used, so that you are able
-to upgrade after performing your own validation. Each install method has a different syntax for setting the version --
-the following are some simple examples:
-
-```bash
-curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0
-# or
-curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 -
-
-pipx install poetry==1.2.0
-
-/path/to/venv/bin/pip install poetry==1.2.0
-```
 {{< /tab >}}
 {{< /tabs >}}
 

Diff for: docs/cli.md

@@ -698,8 +698,17 @@ The table below illustrates the effect of these rules with concrete examples.
 | prerelease | 1.0.3a0 | 1.0.3a1 |
 | prerelease | 1.0.3b0 | 1.0.3b1 |
 
+The option `--next-phase` allows the increment of prerelease phase versions.
+
+| rule                    | before   | after    |
+|-------------------------|----------|----------|
+| prerelease --next-phase | 1.0.3a0  | 1.0.3b0  |
+| prerelease --next-phase | 1.0.3b0  | 1.0.3rc0 |
+| prerelease --next-phase | 1.0.3rc0 | 1.0.3    |
+
 ### Options
 
+* `--next-phase`: Increment the phase of the current version.
 * `--short (-s)`: Output the version number only.
 * `--dry-run`: Do not update pyproject.toml file.
 
@@ -880,6 +889,13 @@ Use of these commands will create the required `pyproject.toml` and `poetry.lock
 [configuration directory]({{< relref "configuration" >}}).
 {{% /note %}}
 
+{{% warning %}}
+Especially on Windows, `self` commands that update or remove packages may be problematic
+so that other methods for installing plugins and updating Poetry are recommended.
+See [Using plugins]({{< relref "plugins#using-plugins" >}}) and
+[Installing Poetry]({{< relref "docs#installation" >}}) for more information.
+{{% /warning %}}
+
 ### self add
 
 The `self add` command installs Poetry plugins and make them available at runtime. Additionally, it can

Diff for: docs/faq.md

@@ -163,7 +163,7 @@ In this case, you can disable this feature by setting the `virtualenvs.create` s
 poetry config virtualenvs.create false
 ```
 
-### Why is Poetry telling me that the current project's Python requirement is not compatible with one or more packages' Python requirements?
+### Why is Poetry telling me that the current project's supported Python range is not compatible with one or more packages' Python requirements?
 
 Unlike `pip`, Poetry doesn't resolve for just the Python in the current environment. Instead it makes sure that a dependency
 is resolvable within the given Python version range in `pyproject.toml`.
@@ -179,18 +179,18 @@ This means your project aims to be compatible with any Python version >=3.7,<4.0
 whose Python requirement doesn't match the whole range Poetry will tell you this, e.g.:
 
 ```
-The current project's Python requirement (>=3.7.0,<4.0.0) is not compatible with some of the required packages Python requirement:
+The current project's supported Python range (>=3.7.0,<4.0.0) is not compatible with some of the required packages Python requirement:
     - scipy requires Python >=3.7,<3.11, so it will not be satisfied for Python >=3.11,<4.0.0
 ```
 
-Usually you will want to match the Python requirement of your project with the upper bound of the failing dependency.
-Alternative you can tell Poetry to install this dependency [only for a specific range of Python versions]({{< relref "dependency-specification#multiple-constraints-dependencies" >}}),
+Usually you will want to match the supported Python range of your project with the upper bound of the failing dependency.
+Alternatively you can tell Poetry to install this dependency [only for a specific range of Python versions]({{< relref "dependency-specification#multiple-constraints-dependencies" >}}),
 if you know that it's not needed in all versions.
 
 
 ### Why does Poetry enforce PEP 440 versions?
 
-This is done so to be compliant with the broader Python ecosystem.
+This is done to be compliant with the broader Python ecosystem.
 
 For example, if Poetry builds a distribution for a project that uses a version that is not valid according to
 [PEP 440](https://peps.python.org/pep-0440), third party tools will be unable to parse the version correctly.

Diff for: docs/managing-environments.md

@@ -22,7 +22,7 @@ By default, Poetry will try to use the Python version used during Poetry's insta
 to create the virtual environment for the current project.
 
 However, for various reasons, this Python version might not be compatible
-with the `python` requirement of the project. In this case, Poetry will try
+with the `python` range supported by the project. In this case, Poetry will try
 to find one that is and use it. If it's unable to do so then you will be prompted
 to activate one explicitly, see [Switching environments](#switching-between-environments).