Update "Python versions" documentation (#4943)

Replacing references to toolchains

docs/SUMMARY.md

@@ -18,7 +18,7 @@
 
 - [Projects](preview/projects.md)
 - [Command-line tools](preview/tools.md)
-- [Python toolchains](preview/toolchains.md)
+- [Python versions](python-versions.md)
 - [Workspaces](preview/workspaces.md)
 - [Dependency sources](preview/dependencies.md)
 - [Resolution](resolution.md)

docs/guides/install-python.md

@@ -26,7 +26,7 @@ To install a specific Python version:
 $ uv python install 3.12
 ```
 
-See the [Python toolchain](../preview/toolchains.md) documentation for more details.
+See the [Python versions](../python-versions.md) documentation for more details.
 
 ## Viewing Python installations
 

docs/python-versions.md

@@ -1,12 +1,12 @@
 **Warning: This documentation refers to experimental features that may change.**
 
-# Toolchains
+# Python versions
 
-A Python toolchain is composed of a Python interpreter (i.e. the `python` executable), the standard library, and other supporting files. It is common for an operating system to come with a Python toolchain installed and there are many tools to help manage Python toolchains.
+A Python installation is composed of a Python interpreter (i.e. the `python` executable), the standard library, and other supporting files. It is common for an operating system to come with a Python version installed and there are many tools to help manage Python versions.
 
-## Requesting a toolchain
+## Requesting a version
 
-uv will automatically download a toolchain if it cannot be found.
+uv will automatically download a Python version if it cannot be found.
 
 In stable commands, this behavior requires enabling preview mode. For example, when creating a virtual environment:
 
@@ -22,7 +22,7 @@ For commands that are in preview, like `uv sync`, preview behavior is always on.
 uv sync --python 3.12.3
 ```
 
-Many toolchain request formats are supported:
+Many Python version request formats are supported:
 
 - `<version>` e.g. `3`, `3.12`, `3.12.3`
 - `<version-specifier>` e.g. `>=3.12,<3.13`
@@ -34,11 +34,11 @@ Many toolchain request formats are supported:
 
 At this time, only CPython downloads are supported. However, PyPy support is planned.
 
-## Installing a toolchain
+## Installing a Python version
 
-Sometimes it is preferable to install the toolchains before they are needed.
+Sometimes it is preferable to install the Python versions before they are needed.
 
-To install a toolchain at a specific version:
+To install a Python version at a specific version:
 
 ```bash
 uv python install 3.12.3
@@ -62,21 +62,21 @@ To install multiple versions:
 uv python install 3.9 3.10 3.11
 ```
 
-## Installing project toolchains
+## Project Python versions
 
-By default `uv python install` will verify that a managed toolchain is installed or install the latest version.
+By default `uv python install` will verify that a managed Python version is installed or install the latest version.
 
-However, a project may define a `.python-version` file specifying the default Python toolchain to be used. If present,
-uv will install the toolchain listed in the file.
+However, a project may define a `.python-version` file specifying the default Python version to be used. If present,
+uv will install the Python version listed in the file.
 
 Alternatively, a project that requires multiple Python versions may also define a `.python-versions` file. If present,
-uv will install all of the toolchains listed in the file. This file takes precedence over the `.python-version` file.
+uv will install all of the Python versions listed in the file. This file takes precedence over the `.python-version` file.
 
 uv will also respect Python requirements defined in a `pyproject.toml` file during project command invocations.
 
-## Viewing available toolchains
+## Viewing available Python versions
 
-To list installed and available toolchains:
+To list installed and available Python versions:
 
 ```bash
 uv python list
@@ -90,37 +90,36 @@ To view all versions:
 uv python list --all-versions
 ```
 
-To view toolchains for other platforms:
+To view Python versions for other platforms:
 
 ```bash
 uv python list --all-platforms
 ```
 
-To exclude downloads and only show installed toolchains:
+To exclude downloads and only show installed Python versions:
 
 ```bash
 uv python list --only-installed
 ```
 
-## Adjusting toolchain preferences
+## Adjusting Python version preferences
 
-By default, uv will attempt to use Python toolchains found on the system and only download managed interpreters when necessary.
-However, It's possible to adjust uv's toolchain selection preference with the `toolchain-preference` option.
+By default, uv will attempt to use Python versions found on the system and only download managed interpreters when necessary.
+However, It's possible to adjust uv's Python version selection preference with the `python-preference` option.
 
-- `only-managed`: Only use managed toolchains, never use system toolchains.
-- `prefer-installed-managed`: Prefer installed managed toolchains, but use system toolchains if not found. If neither can be
-  found, download a managed interpreter.
-- `prefer-managed`: Prefer managed toolchains, even if one needs to be downloaded, but use system toolchains if found.
-- `prefer-system`: Prefer system toolchains, only use managed toolchains if no system interpreter is found.
-- `only-system`: Only use system toolchains, never use managed toolchains.
+- `only-managed`: Only use managed Python installations; never use system Python installations
+- `installed`:    Prefer installed Python installations, only download managed Python installations if no system Python installation is found
+- `managed`:      Prefer managed Python installations over system Python installations, even if fetching is required
+- `system`:       Prefer system Python installations over managed Python installations
+- `only-system`:  Only use system Python installations; never use managed Python installations
 
-These options allow disabling uv's managed toolchains entirely or always using them and ignoring any existing system installations.
+These options allow disabling uv's managed Python versions entirely or always using them and ignoring any existing system installations.
 
 ## Discovery order
 
-When searching for a toolchain, the following locations are checked:
+When searching for a Python version, the following locations are checked:
 
-- Managed toolchains in the `UV_PYTHON_INSTALL_DIR`.
+- Managed Python versions in the `UV_PYTHON_INSTALL_DIR`.
 - A Python interpreter on the `PATH` as `python3` on macOS and Linux, or `python.exe` on Windows.
 - On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
   version.