Improvements to the Python version concepts documentation (#5638)

Depends on #5637

docs/concepts/python-versions.md

@@ -1,14 +1,26 @@
 # Python versions
 
 A Python version 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.
+library, and other supporting files. 
 
-## Requesting a version
+## Managed and system Python installations
+
+Since it is common for a system to have an existing Python installation, uv supports
+[discovering](#discovery-of-python-versions) Python versions. However, uv also supports [installing
+Python versions](#installing-a-python-version) itself. To distinguish between these two types of
+Python installations, uv refers to Python versions it installs as _managed_ Python installations and
+all other Python installations as _system_ Python installations.
+
+!!! note
 
-uv will automatically download a Python version if it cannot be found.
+    uv does not distinguish between Python versions installed by the operating system vs those
+    installed and managed by other tools. For example, if a Python installation is managed with 
+    `pyenv`, it would still be considered a _system_ Python version in uv.
+
+## Requesting a version
 
-For example, when creating a virtual environment:
+A specific Python version can be requested with the `--python` flag in most uv commands. For
+example, when creating a virtual environment:
 
 ```bash
 uv venv --python 3.11.6
@@ -17,7 +29,7 @@ uv venv --python 3.11.6
 uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then
 create the virtual environment with it.
 
-Many Python version request formats are supported:
+The following Python version request formats are supported:
 
 - `<version>` e.g. `3`, `3.12`, `3.12.3`
 - `<version-specifier>` e.g. `>=3.12,<3.13`
@@ -27,12 +39,25 @@ Many Python version request formats are supported:
 - `<implementation><version-specifier>` e.g. `cpython>=3.12,<3.13`
 - `<implementation>-<version>-<os>-<arch>-<libc>` e.g. `cpython-3.12.3-macos-aarch64-none`
 
-## Installing a Python version
+Additionally, a specific system Python interpreter can be requested with:
+
+- `<executable-path>` e.g. `/opt/homebrew/bin/python3`
+- `<executable-name>` e.g. `mypython3`
+- `<install-dir>` e.g. `/some/environment/`
 
-Sometimes it is preferable to install the Python versions before they are needed.
+By default, uv will automatically download Python versions if they cannot be found on the system.
+This behavior can be [disabled with the `python-fetch`
+option](#disabling-automatic-python-downloads).
+
+## Installing a Python version
 
 uv bundles a list of downloadable CPython and PyPy distributions for macOS, Linux, and Windows.
 
+!!! tip
+
+    By default, Python versions are automatically downloaded as needed without using
+    `uv python install`.
+
 To install a Python version at a specific version:
 
 ```bash
@@ -100,50 +125,89 @@ To exclude downloads and only show installed Python versions:
 uv python list --only-installed
 ```
 
+## Discovery of Python versions
+
+When searching for a Python version, the following locations are checked:
+
+- Managed Python installations in the `UV_PYTHON_INSTALL_DIR`.
+- A Python interpreter on the `PATH` as `python`, `python3`, or `python3.x` on macOS and Linux, or `python.exe`
+  on Windows.
+- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
+  version.
+
+When performing discovery, non-executable files will be ignored. Each discovered executable is
+queried for metadata to ensure it meets the [requested Python version](#requesting-a-version). If
+the query fails, the executable will be skipped.
+
+If a Python version cannot be found on the system, uv will check for a compatible managed Python
+version download.
+
+## Disabling automatic Python downloads
+
+By default, uv will automatically download Python versions when needed.
+
+The `python-fetch` option can be used to disable this behavior. By default, it is set to
+`automatic`; set to `manual` to only allow Python downloads during `uv python install`.
+
 ## Adjusting Python version preferences
 
 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.
+interpreters when necessary. 
+
+The `python-preference` option can be used to adjust this behavior. By default, it is set to
+`managed` which prefers managed Python installations over system Python installations. However,
+system Python installations are still preferred over downloading a managed Python version.
+
+The following alternative options are available:
 
 - `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 Python versions entirely or always using them and
 ignoring any existing system installations.
 
-## Discovery order
+!!! note
 
-When searching for a Python version, the following locations are checked:
+    Automatic Python version downloads can be [disabled](#disabling-automatic-python-downloads)
+    without changing the preference.
 
-- 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.
+## Python implementation support
+
+uv supports the CPython, PyPy, and GraalPy Python implementations. If a Python implementation is not
+supported, uv will fail to discover its interpreter.
+
+The implementations may be requested with either the long or short name:
 
-If a specific Python version is requested, e.g. `--python 3.7`, additional executable names are
-included in the search:
+- CPython: `cpython`, `cp`
+- PyPy: `pypy`, `pp`
+- GraalPy: `graalpy`, `gp`
 
-- A Python interpreter on the `PATH` as, e.g., `python3.7` on macOS and Linux.
+Implementation name requests are not case sensitive.
 
-## Python distributions
+See the [Python version request](#requesting-a-version) documentation for more details on the
+supported formats.
+
+## Managed Python distributions
+
+uv supports downloading and installing CPython and PyPy distributions.
+
+### CPython distributions
 
 Python does not publish official distributable CPython binaries, uv uses third-party standalone
 distributions from the
 [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The
 project is partially maintained by the uv maintainers and is used by many other Python projects.
 
-The Python distributions are self-contained and highly-portable. Additionally, these distributions
-have various build-time optimizations enabled to ensure they are performant.
+The uv Python distributions are self-contained, highly-portable, and performant. While
+Python can be built from source, as in tools like `pyenv`, it requires preinstalled system
+dependencies and creating optimized, performant builds is very slow.
 
 These distributions have some behavior quirks, generally as a consequence of portability. See the
 [`python-build-standalone`
 quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation for
 details. 
 
+### PyPy distributions
+
 PyPy distributions are provided by the PyPy project.