Support managing Python 3.13 distributions (#1753)

.github/workflows/test.yml

@@ -24,7 +24,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
 
     steps:
     - uses: actions/checkout@v4
@@ -115,7 +115,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
 
     steps:
     - uses: actions/checkout@v4

docs/plugins/environment/virtual.md

@@ -68,15 +68,16 @@ The following options are recognized for internal Python resolution.
 | `3.10` |
 | `3.11` |
 | `3.12` |
+| `3.13` |
 
 The source of distributions is the [python-build-standalone](https://github.com/indygreg/python-build-standalone) project.
 
-Some distributions have [variants](https://gregoryszorc.com/docs/python-build-standalone/main/running.html) that may be configured with the `HATCH_PYTHON_VARIANT_<PLATFORM>` environment variable where `<PLATFORM>` is the uppercase version of one of the following:
+Some distributions have [variants](https://gregoryszorc.com/docs/python-build-standalone/main/running.html) that may be configured. Options may be combined.
 
-| Platform | Options |
-| --- | --- |
-| Linux | <ul><li><code>v1</code></li><li><code>v2</code></li><li><code>v3</code> (default)</li><li><code>v4</code></li></ul> |
-| Windows | <ul><li><code>shared</code> (default)</li><li><code>static</code></li></ul> |
+| Option | Platforms | Allowed values |
+| --- | --- | --- |
+| `HATCH_PYTHON_VARIANT_CPU` | <ul><li>Linux</li></ul> | <ul><li><code>v1</code></li><li><code>v2</code></li><li><code>v3</code> (default)</li><li><code>v4</code></li></ul> |
+| `HATCH_PYTHON_VARIANT_GIL` | <ul><li>Linux</li><li>Windows</li><li>macOS</li></ul> | <ul><li><code>freethreaded</code></li></ul> |
 
 ### PyPy
 

docs/tutorials/python/manage.md

@@ -70,21 +70,23 @@ $ hatch python show
 ┏━━━━━━┳━━━━━━━━━┓
 ┃ Name ┃ Version ┃
 ┡━━━━━━╇━━━━━━━━━┩
-│ 3.12 │ 3.12.3  │
+│ 3.12 │ 3.12.7  │
 └──────┴─────────┘
       Available
 ┏━━━━━━━━━━┳━━━━━━━━━┓
 ┃ Name     ┃ Version ┃
 ┡━━━━━━━━━━╇━━━━━━━━━┩
 │ 3.7      │ 3.7.9   │
 ├──────────┼─────────┤
-│ 3.8      │ 3.8.19  │
+│ 3.8      │ 3.8.20  │
 ├──────────┼─────────┤
-│ 3.9      │ 3.9.19  │
+│ 3.9      │ 3.9.20  │
 ├──────────┼─────────┤
-│ 3.10     │ 3.10.14 │
+│ 3.10     │ 3.10.15 │
 ├──────────┼─────────┤
-│ 3.11     │ 3.11.9  │
+│ 3.11     │ 3.11.10 │
+├──────────┼─────────┤
+│ 3.13     │ 3.13.0  │
 ├──────────┼─────────┤
 │ pypy2.7  │ 7.3.15  │
 ├──────────┼─────────┤

docs/why.md

@@ -33,7 +33,6 @@ Here we compare to both `tox` and `nox`. At a high level, there are a few common
     In Hatch, [environments](environment.md) are treated as isolated areas where you can execute arbitrary commands at runtime. For example, you can define a single test environment with named [scripts](config/environment/overview.md#scripts) that runs unit vs non-unit tests, each command being potentially very long but named however you wish so you get to control the interface. Since environments are treated as places where work is performed, you can also [spawn a shell](environment.md#entering-environments) into any which will execute a subprocess that automatically drops into your [shell of choice](config/hatch.md#shell). Your shell will be configured appropriately like `python` on PATH being updated and the prompt being changed to reflect the chosen environment.
 
 - **Configuration:**
-    - `tox` only supports INI configuration and if one desires putting that in the standard `pyproject.toml` file then [it must be](https://tox.wiki/en/4.11.4/config.html#pyproject-toml) a multi-line string containing the INI config which would preclude syntax highlighting. Hatch allows for TOML-based config just like most other tools in the Python ecosystem.
     - `nox` config is defined in Python which often leads to increased verbosity and makes it challenging to onboard folks compared to a standardized format with known behaviors.
 - **Extensibility:**
     - `tox` allows for [extending](https://tox.wiki/en/4.11.4/plugins_api.html) most aspects of its functionality however the API is so low-level and attached to internals that creating plugins may be challenging. For example, [here](https://github.com/DataDog/integrations-core/blob/4f4cf10613797e97e7155c75859532a0732d1dff/datadog_checks_dev/datadog_checks/dev/plugin/tox.py) is a `tox` plugin that was [migrated](https://github.com/DataDog/integrations-core/blob/4eb2a1d530bcf810542cf9e45b48fadc7057301c/datadog_checks_dev/datadog_checks/dev/plugin/hatch/environment_collector.py#L100-L148) to an equivalent Hatch [environment collector plugin](plugins/environment-collector/reference.md).

pyproject.toml

@@ -33,6 +33,7 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
   "Topic :: Software Development :: Build Tools",

scripts/update_distributions.py

@@ -11,8 +11,8 @@
 OUTPUT_FILE = ROOT / 'src' / 'hatch' / 'python' / 'distributions.py'
 ARCHES = {('linux', 'x86'): 'i686', ('windows', 'x86_64'): 'amd64', ('windows', 'x86'): 'i386'}
 
-# system, architecture, ABI, variant
-MAX_IDENTIFIER_COMPONENTS = 4
+# system, architecture, ABI, CPU variant, GIL variant
+MAX_IDENTIFIER_COMPONENTS = 5
 
 
 def parse_distributions(contents: str, constant: str):
@@ -34,9 +34,9 @@ def parse_distributions(contents: str, constant: str):
         elif os == 'macos' and arch == 'aarch64':
             arch = 'arm64'
 
-        # Force everything to have a variant to maintain structure
+        # Force everything to have the proper number of variants to maintain structure
         if len(data) != MAX_IDENTIFIER_COMPONENTS:
-            data.append('')
+            data.extend(('', ''))
 
         data[1] = ARCHES.get((os, arch), arch)
         yield identifier, tuple(data), source

src/hatch/env/internal/test.py

@@ -21,5 +21,5 @@ def get_default_config() -> dict[str, Any]:
             'cov-combine': 'coverage combine',
             'cov-report': 'coverage report',
         },
-        'matrix': [{'python': ['3.12', '3.11', '3.10', '3.9', '3.8']}],
+        'matrix': [{'python': ['3.13', '3.12', '3.11', '3.10', '3.9', '3.8']}],
     }