feat(cli): introduce python management commands (#10112)

Co-authored-by: Randy Döring <[email protected]>

Author: abn

docs/cli.md

@@ -726,6 +726,56 @@ Should match a repository name set by the [`config`](#config) command.
 See [Configuring Credentials]({{< relref "repositories/#configuring-credentials" >}}) for more information on how to configure credentials.
 {{% /note %}}
 
+## python
+
+The `python` namespace groups subcommands to manage Python versions.
+
+{{% warning %}}
+This is an experimental feature, and can change behaviour in upcoming releases.
+{{% /warning %}}
+
+*Introduced in 2.1.0*
+
+### python install
+
+The `python install` command installs the specified Python version from the Python Standalone Builds project.
+
+```bash
+poetry python install <PYTHON_VERSION>
+```
+
+#### Options
+
+* `--clean`: Clean up installation if check fails.
+* `--free-threaded`: Use free-threaded version if available.
+* `--implementation`: Python implementation to use. (cpython, pypy)
+* `--reinstall`: Reinstall if installation already exists.
+
+### python list
+
+The `python list` command shows Python versions available in the environment. This includes both installed and
+discovered System managed and Poetry managed installations.
+
+```bash
+poetry python list
+```
+#### Options
+* `--all`: List all versions, including those available for download.
+* `--implementation`: Python implementation to search for.
+* `--managed`: List only Poetry managed Python versions.
+
+### python remove
+
+The `python remove` command removes the specified Python version if managed by Poetry.
+
+```bash
+poetry python remove <PYTHON_VERSION>
+```
+
+#### Options
+
+* `--implementation`: Python implementation to use. (cpython, pypy)
+
 ## remove
 
 The `remove` command removes a package from the current

docs/configuration.md

@@ -139,23 +139,23 @@ Poetry uses the following default directories:
 - Windows: `%APPDATA%\pypoetry`
 - macOS: `~/Library/Application Support/pypoetry`
 
-You can override the Config directory by setting the `POETRY_CONFIG_DIR` environment variable.
+You can override the config directory by setting the `POETRY_CONFIG_DIR` environment variable.
 
 ### Data Directory
 
 - Linux: `$XDG_DATA_HOME/pypoetry` or `~/.local/share/pypoetry`
 - Windows: `%APPDATA%\pypoetry`
 - macOS: `~/Library/Application Support/pypoetry`
 
-You can override the Data directory by setting the `POETRY_DATA_DIR` or `POETRY_HOME` environment variables. If `POETRY_HOME` is set, it will be given higher priority.
+You can override the data directory by setting the `POETRY_DATA_DIR` or `POETRY_HOME` environment variables. If `POETRY_HOME` is set, it will be given higher priority.
 
 ### Cache Directory
 
 - Linux: `$XDG_CACHE_HOME/pypoetry` or `~/.cache/pypoetry`
 - Windows: `%LOCALAPPDATA%\pypoetry`
 - macOS: `~/Library/Caches/pypoetry`
 
-You can override the Cache directory by setting the `POETRY_CACHE_DIR` environment variable.
+You can override the cache directory by setting the `POETRY_CACHE_DIR` environment variable.
 
 ## Available settings
 
@@ -173,6 +173,21 @@ Defaults to one of the following directories:
 - Windows: `C:\Users\<username>\AppData\Local\pypoetry\Cache`
 - Unix:    `~/.cache/pypoetry`
 
+### `data-dir`
+
+**Type**: `string`
+
+**Environment Variable**: `POETRY_DATA_DIR`
+
+The path to the data directory used by Poetry.
+
+- Linux: `$XDG_DATA_HOME/pypoetry` or `~/.local/share/pypoetry`
+- Windows: `%APPDATA%\pypoetry`
+- macOS: `~/Library/Application Support/pypoetry`
+
+You can override the data directory by setting the `POETRY_DATA_DIR` or `POETRY_HOME` environment variables. If
+`POETRY_HOME` is set, it will be given higher priority.
+
 ### `installer.max-workers`
 
 **Type**: `int`
@@ -342,6 +357,18 @@ If the config option is _not_ set and the lock file is at least version 2.1
 but evaluate the locked markers to decide which of the locked dependencies have to
 be installed into the target environment.
 
+### `python.installation-dir`
+
+**Type**: `string`
+
+**Default**: `{data-dir}/python`
+
+**Environment Variable**: `POETRY_PYTHON_INSTALLATION_DIR`
+
+*Introduced in 2.1.0*
+
+The directory in which Poetry managed Python versions are installed to.
+
 ### `solver.lazy-wheel`
 
 **Type**: `boolean`