Document support for free-threaded and debug Python versions (#15961)

Closes #12707

---------

Co-authored-by: Geoffrey Thomas <geofft@ldpreload.com>

docs/concepts/python-versions.md

@@ -33,6 +33,8 @@ 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`)
+- `<version><short-variant>` (e.g., `3.13t`, `3.12.0d`)
+- `<version>+<variant>` (e.g., `3.13+freethreaded`, `3.12.0+debug`)
 - `<implementation>` (e.g., `cpython` or `cp`)
 - `<implementation>@<version>` (e.g., `cpython@3.12`)
 - `<implementation><version>` (e.g., `cpython3.12` or `cp312`)
@@ -315,7 +317,7 @@ a system Python version, uv will use the first compatible version — not the ne
 If a Python version cannot be found on the system, uv will check for a compatible managed Python
 version download.
 
-### Python pre-releases
+## Python pre-releases
 
 Python pre-releases will not be selected by default. Python pre-releases will be used if there is no
 other available installation matching the request. For example, if only a pre-release version is
@@ -326,6 +328,38 @@ and the pre-release version will be used.
 If a pre-release Python version is available and matches the request, uv will not download a stable
 Python version instead.
 
+## Free-threaded Python
+
+uv supports discovering and installing
+[free-threaded](https://docs.python.org/3.14/glossary.html#term-free-threading) Python variants in
+CPython 3.13+.
+
+Free-threaded Python versions will not be selected by default. Free-threaded Python versions will
+only be selected when explicitly requested, e.g., with `3.13t` or `3.13+freethreaded`.
+
+## Debug Python variants
+
+uv supports discovering and installing
+[debug builds](https://docs.python.org/3.14/using/configure.html#debug-build) of Python, i.e., with
+debug assertions enabled.
+
+!!! important
+
+    Debug builds of Python are slower and are not appropriate for general use.
+
+Debug builds will be used if there is no other available installation matching the request. For
+example, if only a debug version is available it will be used but otherwise a stable release version
+will be used. Similarly, if the path to a debug Python executable is provided then no other Python
+version matches the request and the debug version will be used.
+
+Debug builds of Python can be explicitly requested with, e.g., `3.13d` or `3.13+debug`.
+
+!!! note
+
+    CPython versions installed by uv usually have debug symbols stripped to reduce the distribution
+    size. These debug builds do not have debug symbols stripped, which can be useful when debugging
+    Python processes with a C-level debugger.
+
 ## Disabling automatic Python downloads
 
 By default, uv will automatically download Python versions when needed.