python-discovery 1.6.6__tar.gz → 1.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. python_discovery-1.7.0/.github/SECURITY.md +56 -0
  2. python_discovery-1.7.0/.github/THREAT_MODEL.md +106 -0
  3. {python_discovery-1.6.6 → python_discovery-1.7.0}/.github/workflows/news.yaml +3 -2
  4. {python_discovery-1.6.6 → python_discovery-1.7.0}/.github/workflows/prepare-release.yaml +1 -1
  5. {python_discovery-1.6.6 → python_discovery-1.7.0}/.github/workflows/release.yaml +6 -6
  6. {python_discovery-1.6.6 → python_discovery-1.7.0}/.github/workflows/upgrade-release-tools.yaml +1 -1
  7. {python_discovery-1.6.6 → python_discovery-1.7.0}/PKG-INFO +1 -1
  8. python_discovery-1.7.0/docs/_static/github.svg +1 -0
  9. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/changelog.rst +50 -0
  10. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/conf.py +16 -3
  11. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/explanation.rst +12 -3
  12. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_discovery.py +17 -7
  13. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_py_info.py +5 -1
  14. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_py_spec.py +52 -39
  15. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_discovery.py +78 -1
  16. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_iter_interpreters.py +36 -0
  17. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_py_info_extra.py +45 -0
  18. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_py_spec.py +44 -9
  19. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_py_spec_extra.py +0 -5
  20. python_discovery-1.6.6/.github/SECURITY.md +0 -9
  21. {python_discovery-1.6.6 → python_discovery-1.7.0}/.github/FUNDING.yaml +0 -0
  22. {python_discovery-1.6.6 → python_discovery-1.7.0}/.github/dependabot.yaml +0 -0
  23. {python_discovery-1.6.6 → python_discovery-1.7.0}/.github/release.yaml +0 -0
  24. {python_discovery-1.6.6 → python_discovery-1.7.0}/.github/workflows/check.yaml +0 -0
  25. {python_discovery-1.6.6 → python_discovery-1.7.0}/.github/workflows/codeql.yaml +0 -0
  26. {python_discovery-1.6.6 → python_discovery-1.7.0}/.gitignore +0 -0
  27. {python_discovery-1.6.6 → python_discovery-1.7.0}/.pre-commit-config.yaml +0 -0
  28. {python_discovery-1.6.6 → python_discovery-1.7.0}/.readthedocs.yaml +0 -0
  29. {python_discovery-1.6.6 → python_discovery-1.7.0}/.readthedocs.yml +0 -0
  30. {python_discovery-1.6.6 → python_discovery-1.7.0}/CODE_OF_CONDUCT.md +0 -0
  31. {python_discovery-1.6.6 → python_discovery-1.7.0}/LICENSE +0 -0
  32. {python_discovery-1.6.6 → python_discovery-1.7.0}/README.md +0 -0
  33. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/_static/custom.css +0 -0
  34. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/_static/logo.svg +0 -0
  35. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/changelog/template.jinja2 +0 -0
  36. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/contributing.rst +0 -0
  37. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/how-to/standalone-usage.rst +0 -0
  38. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/index.rst +0 -0
  39. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/reference/api.rst +0 -0
  40. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/reference/environment-variables.rst +0 -0
  41. {python_discovery-1.6.6 → python_discovery-1.7.0}/docs/tutorial/getting-started.rst +0 -0
  42. {python_discovery-1.6.6 → python_discovery-1.7.0}/pylock.toml +0 -0
  43. {python_discovery-1.6.6 → python_discovery-1.7.0}/pyproject.toml +0 -0
  44. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/__init__.py +0 -0
  45. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_cache.py +0 -0
  46. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_cached_py_info.py +0 -0
  47. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_compat.py +0 -0
  48. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_py_info_collect.py +0 -0
  49. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_specifier.py +0 -0
  50. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_windows/__init__.py +0 -0
  51. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_windows/_pep514.py +0 -0
  52. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/_windows/_propose.py +0 -0
  53. {python_discovery-1.6.6 → python_discovery-1.7.0}/src/python_discovery/py.typed +0 -0
  54. {python_discovery-1.6.6 → python_discovery-1.7.0}/tasks/old_target_check.py +0 -0
  55. {python_discovery-1.6.6 → python_discovery-1.7.0}/tasks/old_target_check.sh +0 -0
  56. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/conftest.py +0 -0
  57. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/py_info/test_py_info.py +0 -0
  58. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/py_info/test_py_info_exe_based_of.py +0 -0
  59. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_cache.py +0 -0
  60. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_cache_recovery.py +0 -0
  61. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_cached_py_info.py +0 -0
  62. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_discovery_extra.py +0 -0
  63. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_py_info_collect.py +0 -0
  64. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_query_timeout.py +0 -0
  65. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/test_specifier.py +0 -0
  66. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/windows/conftest.py +0 -0
  67. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/windows/test_windows.py +0 -0
  68. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/windows/test_windows_pep514.py +0 -0
  69. {python_discovery-1.6.6 → python_discovery-1.7.0}/tests/windows/winreg_mock_values.py +0 -0
  70. {python_discovery-1.6.6 → python_discovery-1.7.0}/tox.toml +0 -0
@@ -0,0 +1,56 @@
1
+ # Security policy
2
+
3
+ python-discovery is a Python library that finds Python interpreters on a machine and reports their metadata. This policy
4
+ says how to report a security problem and how we decide whether a report is one.
5
+
6
+ ## Reporting a vulnerability
7
+
8
+ **Do not open a public issue for a security problem.** Use
9
+ [GitHub's private vulnerability reporting](https://github.com/tox-dev/python-discovery/security/advisories/new). If
10
+ neither works for you, email [gaborjbernat@gmail.com](mailto:gaborjbernat@gmail.com).
11
+
12
+ Include what the attacker controls and what they gain, the steps or a proof of concept, and the versions and platform
13
+ you tested. Write the report yourself; unreviewed tool or model output takes longer to triage.
14
+
15
+ ## What to expect
16
+
17
+ Volunteers maintain python-discovery, with no on-call rotation. We aim to acknowledge a report within **5 working days**
18
+ and assess it within **15 working days**. Fixes are developed in a private fork attached to the draft advisory, ship in
19
+ a new release, and the advisory, with a CVE requested through GitHub, goes out with that release. The default embargo is
20
+ **90 days** from the report; we agree any change with the reporter. We credit reporters in the advisory under the name
21
+ they choose, or not at all. There is no bug bounty.
22
+
23
+ ## Supported versions
24
+
25
+ Only the latest release receives fixes. Confirm the problem reproduces on it before reporting.
26
+
27
+ ## Vulnerability or bug
28
+
29
+ A report is a vulnerability when an attacker who controls only an input that the [threat model](THREAT_MODEL.md) lists
30
+ as untrusted breaks a guarantee python-discovery makes. A report that first needs control of something the threat model
31
+ trusts, such as an executable on `PATH` or in a version manager's directory, is a bug: we fix it in the open and publish
32
+ no advisory. Classify by who supplies the dangerous input, not by how bad the outcome sounds.
33
+
34
+ **In scope**
35
+
36
+ - Executing a binary from a location the documented search order does not include, such as the current directory through
37
+ an empty `PATH` entry.
38
+ - A cache entry from one interpreter being reported for another, or surviving a change of the binary.
39
+ - Interrogation output from one candidate being parsed as another candidate's metadata.
40
+ - A spec's version, implementation, architecture, free-threading or debug constraint passing for a shim or launcher
41
+ while the interpreter it resolves to fails it.
42
+ - A PEP 514 record or a spec making discovery run a program other than the candidate with its registered arguments.
43
+ - Another local user writing a shared cache directory so a victim accepts an interpreter, or metadata, that discovery
44
+ would otherwise reject.
45
+ - A small candidate response exhausting memory or processes.
46
+
47
+ **Out of scope**
48
+
49
+ - A malicious interpreter in a searched location: python-discovery runs candidates to learn about them, so whoever can
50
+ place one there already runs code as the user.
51
+ - Values in the process environment (`PATH`, `PYENV_ROOT`, `UV_PYTHON_INSTALL_DIR`, `PY_DISCOVERY_TIMEOUT`) and the
52
+ Windows registry entries of PEP 514.
53
+ - A `.python-version` file choosing among interpreters that discovery would find anyway.
54
+ - Tampering with a cache directory only the caller can write.
55
+
56
+ If you cannot tell which side a finding falls on, report it privately and we will decide.
@@ -0,0 +1,106 @@
1
+ # Threat model
2
+
3
+ This model says what python-discovery trusts, where untrusted input enters, and which guarantees hold at each boundary,
4
+ so a report can be classified as a vulnerability or a bug. [SECURITY.md](SECURITY.md) covers reporting; if the two
5
+ disagree, SECURITY.md wins and we fix this file.
6
+
7
+ ## How python-discovery works
8
+
9
+ A caller passes a requirement such as `python3.12` or `>=3.11,<3.13`. python-discovery walks `try_first_with` paths, the
10
+ running interpreter, the PEP 514 registry on Windows, `PATH` (resolving pyenv, mise and asdf shims to the binary they
11
+ select), and uv's install directories. It runs each candidate with a bundled interrogation script and reads a JSON
12
+ answer framed by two random cookies, then caches that answer in a directory the caller supplies, valid while the
13
+ binary's path and modification time, the script's hash and any PEP 514 arguments stay the same.
14
+
15
+ ```mermaid
16
+ flowchart LR
17
+ caller["Caller<br/>spec, env, cache dir (trusted)"] --> pd["python-discovery"]
18
+ pd -->|search| locs[("PATH, version managers,<br/>PEP 514 registry (trusted)")]
19
+ pd -->|"run candidate + script"| py["Candidate interpreter"]
20
+ py -->|"JSON between cookies"| pd
21
+ pd <-->|"checked against path, mtime,<br/>script hash, PEP 514 args"| cache[("Cache dir")]
22
+ classDef trusted fill:#cfe4ff,stroke:#1f6feb,color:#0b1f3a;
23
+ classDef boundary fill:#ffe3a3,stroke:#d29200,color:#3a2c00;
24
+ class caller,pd,locs trusted;
25
+ class py,cache boundary;
26
+ ```
27
+
28
+ ## Compared with similar tools
29
+
30
+ We drew the boundary where comparable projects in other ecosystems draw theirs. The shared rule, stated by the
31
+ [Node.js threat model](https://github.com/nodejs/node/blob/main/SECURITY.md#the-nodejs-threat-model), is that a report
32
+ which first needs a trusted element compromised is out of scope; the first triage question, as
33
+ [DOMPurify](https://github.com/cure53/DOMPurify/blob/main/SECURITY.md#what-we-consider-a-vulnerability) puts it, is what
34
+ the attacker controls.
35
+
36
+ | Project | Language | Where it draws the line |
37
+ | ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
38
+ | [Go `os/exec` path lookup](https://go.dev/blog/path-security) | Go | Refuses to run a binary found through the current directory; python-discovery skips empty `PATH` entries for the same reason. |
39
+ | [nvm](https://github.com/nvm-sh/nvm/blob/HEAD/.github/THREAT_MODEL.md) | Shell | Trusts what it installs and executes as the user; treats mirror metadata, not payloads, as the untrusted boundary. |
40
+ | [uv](https://github.com/astral-sh/uv/security/policy) | Rust | Its policy says invoking the Python interpreters it finds, to read their metadata, is not a vulnerability. |
41
+
42
+ ## Trusted
43
+
44
+ An attacker who controls any of these already has what python-discovery could give them:
45
+
46
+ - The caller and the spec, environment mapping, cache directory and `try_first_with` paths it passes.
47
+ - Every directory searched: `PATH` entries, version-manager roots and install directories, and the PEP 514 registry,
48
+ including `ExecutableArguments`.
49
+ - The interpreters found there; running them is how discovery works.
50
+ - A cache directory that only the caller can write (for example virtualenv's app-data).
51
+
52
+ ## Untrusted inputs
53
+
54
+ | Input | Comes from | What python-discovery guarantees |
55
+ | ----------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
56
+ | The current working directory | Wherever the caller happens to run | Empty `PATH` components, which shells read as the current directory, are skipped. |
57
+ | Interrogation stdout | Startup noise or a `sitecustomize` that prints | Only the JSON between two per-run random cookies is parsed; anything else is a failed candidate. |
58
+ | Cache entries | Earlier runs, possibly of another interpreter build | Reused only when the binary's path and modification time, the script hash and the PEP 514 arguments all match. |
59
+ | A shared cache directory | Another local user who can write it | Must not make a victim accept an interpreter or metadata that discovery would reject; report any way it does. |
60
+
61
+ ## Threats and controls
62
+
63
+ | STRIDE | Threat | Control |
64
+ | ---------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
65
+ | Spoofing | Output printed by a candidate's startup code impersonates its metadata. | Random start and end cookies frame the answer. |
66
+ | Tampering | A stale cache entry describes a binary that has since been replaced. | The entry records the binary's modification time, the script's hash and the PEP 514 arguments. |
67
+ | Denial of service | A candidate hangs during interrogation. | The interrogation has a timeout, configurable with `PY_DISCOVERY_TIMEOUT`. |
68
+ | Elevation of privilege | A binary in the current directory is picked up through `PATH`. | Empty `PATH` entries are skipped. |
69
+
70
+ ## Release chain
71
+
72
+ Releases run on the shared [tox-dev/github-workflows](https://github.com/tox-dev/github-workflows) pipeline. A release
73
+ App, not a person, pushes the release commit and tag; the build installs its tools from a hash-checked `pylock.toml`
74
+ resolved with a seven-day upload cooldown by default; PyPI receives the files through
75
+ [trusted publishing](https://docs.pypi.org/trusted-publishers/) with attestations, and the GitHub Release is immutable.
76
+ Every workflow pins third-party actions to a commit SHA.
77
+
78
+ ## Vulnerability or bug
79
+
80
+ | Report | Verdict | Why |
81
+ | --------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
82
+ | A `python3` in the working directory runs because `PATH` ends with `:` | Vulnerability | The empty entry must not reach the current directory. |
83
+ | A `pyenv` shim that is malware runs during discovery | Not a vulnerability | Searched locations are trusted. |
84
+ | A cached answer for `/usr/bin/python3` is returned after the OS upgraded it | Bug | Cache correctness, crossing no boundary; a vulnerability only if it can point at a different binary. |
85
+ | `PY_DISCOVERY_TIMEOUT=inf` lets a hung interpreter block forever | Not a vulnerability | The environment is trusted and the value is documented. |
86
+
87
+ ## Severity
88
+
89
+ - **High:** argument handling runs a separate command the attacker chose, or another local user poisons a shared cache
90
+ so a victim runs an interpreter outside the requested constraints, without control of the victim's `PATH`, registry or
91
+ interpreters.
92
+ - **Medium:** cache poisoning changes security-relevant metadata without execution, or a small candidate response causes
93
+ sustained memory or process exhaustion.
94
+ - **Low:** the wrong interpreter selected without crossing a privilege boundary, a crash on malformed output, or stale
95
+ metadata from a cache only the caller writes.
96
+
97
+ ## Accepted risks
98
+
99
+ - Discovery executes every candidate it considers; it cannot learn an interpreter's version without running it.
100
+ - PEP 514 `ExecutableArguments` are raw command-line text from the registry, passed to the candidate as written, without
101
+ a shell.
102
+
103
+ ## Keeping this current
104
+
105
+ Revisit this model when python-discovery gains a new input source, network access, a new way to run code, or a new place
106
+ it writes to, and whenever an advisory is published.
@@ -7,6 +7,7 @@ concurrency:
7
7
  cancel-in-progress: true
8
8
  permissions:
9
9
  contents: read
10
+ pull-requests: read
10
11
  jobs:
11
12
  changelog:
12
13
  name: 📝 News fragment
@@ -24,9 +25,9 @@ jobs:
24
25
  python-version: "3.15"
25
26
  enable-cache: false
26
27
  - name: 📦 Install locked release tools
27
- uses: tox-dev/github-workflows/install-locked-tools@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
28
+ uses: tox-dev/github-workflows/install-locked-tools@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
28
29
  with:
29
30
  groups: release-news
30
31
  venv: ${{ runner.temp }}/release-tools
31
32
  - name: 🔍 Validate news fragments
32
- uses: tox-dev/github-workflows/validate-news@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
33
+ uses: tox-dev/github-workflows/validate-news@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
@@ -12,7 +12,7 @@ permissions: {}
12
12
  jobs:
13
13
  prepare:
14
14
  name: 🏷️ Prepare Towncrier release
15
- uses: tox-dev/github-workflows/.github/workflows/prepare-towncrier-release.yaml@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
15
+ uses: tox-dev/github-workflows/.github/workflows/prepare-towncrier-release.yaml@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
16
16
  permissions:
17
17
  contents: read
18
18
  pull-requests: read
@@ -10,7 +10,7 @@ concurrency:
10
10
  jobs:
11
11
  build:
12
12
  name: 🏗️ Build
13
- uses: tox-dev/github-workflows/.github/workflows/validate-python-release.yaml@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
13
+ uses: tox-dev/github-workflows/.github/workflows/validate-python-release.yaml@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
14
14
  permissions:
15
15
  contents: read
16
16
  notes:
@@ -33,17 +33,17 @@ jobs:
33
33
  python-version: "3.15"
34
34
  enable-cache: false
35
35
  - name: 📦 Install locked release tools
36
- uses: tox-dev/github-workflows/install-locked-tools@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
36
+ uses: tox-dev/github-workflows/install-locked-tools@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
37
37
  with:
38
38
  groups: release-notes
39
39
  venv: ${{ runner.temp }}/release-tools
40
40
  - name: 🏷️ Select previous tag
41
41
  id: previous
42
- uses: tox-dev/github-workflows/select-previous-tag@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
42
+ uses: tox-dev/github-workflows/select-previous-tag@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
43
43
  with:
44
44
  tag: ${{ github.ref_name }}
45
45
  - name: 📝 Render release notes
46
- uses: tox-dev/github-workflows/render-release-notes@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
46
+ uses: tox-dev/github-workflows/render-release-notes@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
47
47
  with:
48
48
  tag: ${{ github.ref_name }}
49
49
  previous: ${{ steps.previous.outputs.previous }}
@@ -101,13 +101,13 @@ jobs:
101
101
  artifact-ids: ${{ needs.notes.outputs.artifact-id }}
102
102
  path: ${{ runner.temp }}
103
103
  - name: 🔍 Verify PyPI artifacts
104
- uses: tox-dev/github-workflows/reconcile-pypi-artifacts@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
104
+ uses: tox-dev/github-workflows/reconcile-pypi-artifacts@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
105
105
  with:
106
106
  project: python-discovery
107
107
  version: ${{ github.ref_name }}
108
108
  dist: dist
109
109
  - name: 🚀 Publish GitHub release
110
- uses: tox-dev/github-workflows/publish-github-release@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
110
+ uses: tox-dev/github-workflows/publish-github-release@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
111
111
  env:
112
112
  GH_TOKEN: ${{ github.token }}
113
113
  with:
@@ -10,7 +10,7 @@ concurrency:
10
10
  jobs:
11
11
  upgrade:
12
12
  name: 🔀 Upgrade release tools
13
- uses: tox-dev/github-workflows/.github/workflows/upgrade-release-tools.yaml@259a3d3fb578d00517ffb73341fdd463259b0b2f # 6.0.1
13
+ uses: tox-dev/github-workflows/.github/workflows/upgrade-release-tools.yaml@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
14
14
  permissions:
15
15
  contents: read
16
16
  secrets:
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: python-discovery
3
- Version: 1.6.6
3
+ Version: 1.7.0
4
4
  Import-Name: python_discovery
5
5
  Summary: Python interpreter discovery
6
6
  Project-URL: Changelog, https://github.com/tox-dev/python-discovery/blob/main/docs/changelog.rst
@@ -0,0 +1 @@
1
+ <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path></svg>
@@ -6,6 +6,56 @@
6
6
 
7
7
  .. towncrier release notes start
8
8
 
9
+ .. _release-1-7-0:
10
+
11
+ *********************
12
+ v1.7.0 (2026-10-30)
13
+ *********************
14
+
15
+ .. _release-1-7-0-added:
16
+
17
+ Added
18
+ -----
19
+
20
+ - Accept the free-threaded, debug, architecture and machine suffixes after a version specifier, as in ``>=3.13t`` or
21
+ ``cpython>=3.11,<3.14-64``, and raise ``ValueError`` for a spec that starts with a comparison operator but does not
22
+ parse, such as ``>=3.13.``, instead of looking it up as an executable name (:pr:`176`) by :user:`gaborbernat`.
23
+ (:issue:`175`)
24
+
25
+ .. _release-1-7-0-fixed:
26
+
27
+ Fixed
28
+ -----
29
+
30
+ - Stop a ``.python-version`` file that is not valid UTF-8, or that cannot be read, from aborting discovery through a
31
+ pyenv, mise or asdf shim; a stray byte no longer hides the versions it names, and an unreadable file is skipped like a
32
+ missing one (:pr:`173`) by :user:`darrenhuai` and :user:`gaborbernat`.
33
+
34
+ .. _release-1-7-0-documentation:
35
+
36
+ Documentation
37
+ -------------
38
+
39
+ - Link every documentation page to its source and edit view on GitHub, and add a GitHub icon to the footer (:pr:`177`)
40
+ by :user:`gaborbernat`. (:issue:`174`)
41
+
42
+ .. _release-1-6-7:
43
+
44
+ *********************
45
+ v1.6.7 (2026-10-28)
46
+ *********************
47
+
48
+ .. _release-1-6-7-fixed:
49
+
50
+ Fixed
51
+ -----
52
+
53
+ - Rank uv's minor version links behind the concrete install on Windows too, where uv creates them as directory junctions
54
+ that ``Path.is_symlink()`` does not report (:pr:`170`) by :user:`darrenhuai` and :user:`gaborbernat`.
55
+ - Stop a venv lookup from rewriting the ``executable`` of earlier results, ``PythonInfo.current()`` and
56
+ ``PythonInfo.current_system()`` when they share its base interpreter (:pr:`171`) by :user:`darrenhuai` and
57
+ :user:`gaborbernat`.
58
+
9
59
  .. _release-1-6-6:
10
60
 
11
61
  *********************
@@ -10,6 +10,7 @@ from python_discovery import __version__
10
10
 
11
11
  company = "tox-dev"
12
12
  name = "python-discovery"
13
+ repository = f"https://github.com/{company}/{name}"
13
14
  version = ".".join(__version__.split(".")[:2])
14
15
  release = __version__
15
16
  copyright = f"2026-{datetime.now(tz=timezone.utc).year}, {company}" # ruff:ignore[builtin-variable-shadowing]
@@ -31,9 +32,9 @@ towncrier_draft_working_directory = Path(__file__).parent.parent
31
32
  autosectionlabel_maxdepth = 2
32
33
 
33
34
  extlinks = {
34
- "issue": ("https://github.com/tox-dev/python-discovery/issues/%s", "#%s"),
35
- "pr": ("https://github.com/tox-dev/python-discovery/pull/%s", "PR #%s"),
36
- "pull": ("https://github.com/tox-dev/python-discovery/pull/%s", "PR #%s"),
35
+ "issue": (f"{repository}/issues/%s", "#%s"),
36
+ "pr": (f"{repository}/pull/%s", "PR #%s"),
37
+ "pull": (f"{repository}/pull/%s", "PR #%s"),
37
38
  "user": ("https://github.com/%s", "@%s"),
38
39
  }
39
40
 
@@ -60,6 +61,18 @@ html_theme_options = {
60
61
  "light_logo": "logo.svg",
61
62
  "dark_logo": "logo.svg",
62
63
  "sidebar_hide_name": True,
64
+ "source_repository": repository,
65
+ "source_branch": "main",
66
+ "source_directory": "docs/",
67
+ "footer_icons": [
68
+ {
69
+ "name": "GitHub",
70
+ "url": repository,
71
+ # footer icons are inlined into every page, so a path to the image would not resolve
72
+ "html": (Path(__file__).parent / "_static" / "github.svg").read_text(encoding="utf-8"),
73
+ "class": "",
74
+ },
75
+ ],
63
76
  }
64
77
  html_css_files = ["custom.css"]
65
78
 
@@ -52,7 +52,7 @@ detects these shims and resolves them to the actual binary.
52
52
  flowchart TD
53
53
  Shim["Shim detected"] --> EnvVar{"PYENV_VERSION<br>set?"}
54
54
  EnvVar -->|Yes| Use["Use that version"]
55
- EnvVar -->|No| File{".python-version<br>file exists?"}
55
+ EnvVar -->|No| File{".python-version<br>names a version?"}
56
56
  File -->|Yes| Use
57
57
  File -->|No| Global{"pyenv global<br>version exists?"}
58
58
  Global -->|Yes| Use
@@ -364,10 +364,19 @@ and machine segments, leaves the string unrecognized, so it falls back to a lite
364
364
  * - ``cpython>=3.11``
365
365
  - `Version specifier <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_
366
366
  restricted to CPython
367
+ * - ``>=3.13t``
368
+ - `Version specifier <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_
369
+ restricted to free-threaded builds
367
370
 
368
371
  `Version specifiers <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_
369
372
  (``>=``, ``<=``, ``~=``, ``!=``, ``==``, ``===``) are supported. Multiple specifiers can be comma-separated,
370
373
  for example ``>=3.11,<3.13``. Each version is a release of up to three numbers with an optional ``a``, ``b`` or
371
374
  ``rc`` pre-release suffix, such as ``3.12`` or ``3.13.0rc1``; ``==`` and ``!=`` also take a trailing ``.*``
372
- wildcard, as in ``==3.12.*``. A specifier with any item outside that form, such as ``>=3.x``, ``>=3.10.post1``,
373
- ``>=3.12 <4`` (missing comma) or ``>=3.12,foo``, falls back to a literal executable-name match.
375
+ wildcard, as in ``==3.12.*``.
376
+
377
+ The ABI flags, ``-arch`` and ``-machine`` parts described above follow the last specifier and apply to the whole set:
378
+ ``>=3.13t`` asks for a free-threaded 3.13 or newer, ``cpython>=3.11,<3.14-64`` for a 64-bit CPython in that range.
379
+ Without ``t`` a specifier accepts any build, while a plain ``3.13`` asks for the default (GIL) build. A string that
380
+ starts with a comparison operator but does not parse this way, such as ``>=3.x``, ``>=3.10.post1``, ``>=3.12 <4``
381
+ (missing comma) or ``>=3.13t,<3.15`` (a flag on an inner item), raises :exc:`ValueError` instead of being looked up as
382
+ an executable name.
@@ -389,8 +389,9 @@ def _uv_sort_key(install: _UvInstall) -> tuple[int, ...]:
389
389
  version = key.version
390
390
  return (
391
391
  impl_order.index(key.implementation) if key.implementation in impl_order else len(impl_order),
392
- # uv's minor version links point at a concrete install that moves on upgrade, so report the target instead
393
- int(install.path.is_symlink()),
392
+ # uv's minor version links point at a concrete install that moves on upgrade, so report the target instead;
393
+ # spot them by the name they resolve to, as on Windows they are junctions, which is_symlink() does not report
394
+ int(install.path.resolve().name != install.path.name),
394
395
  -version.major,
395
396
  -version.minor,
396
397
  -version.micro,
@@ -531,11 +532,10 @@ def _read_python_version_file(start: str | Path, *, search_parents: bool = True)
531
532
  """Read a ``.python-version`` file, optionally searching parent directories."""
532
533
  current = start
533
534
  while True:
534
- candidate = os.path.join(current, ".python-version") if Path(current).is_dir() else current
535
- if Path(candidate).is_file():
536
- with Path(candidate).open(encoding="utf-8") as fh:
537
- if versions := [v for line in fh if (v := line.strip()) and not v.startswith("#")]:
538
- return versions
535
+ # unlike pathlib before 3.14, os.path answers False when a directory on the way can't be searched
536
+ candidate = os.path.join(current, ".python-version") if os.path.isdir(current) else current
537
+ if os.path.isfile(candidate) and (versions := _versions_in_file(candidate)):
538
+ return versions
539
539
  if not search_parents:
540
540
  return None
541
541
  parent = Path(current).parent
@@ -544,6 +544,16 @@ def _read_python_version_file(start: str | Path, *, search_parents: bool = True)
544
544
  current = parent
545
545
 
546
546
 
547
+ def _versions_in_file(path: str | Path) -> list[str]:
548
+ try:
549
+ # pyenv reads raw bytes, so a byte that is not UTF-8 (a Latin-1 comment, say) must not hide the versions
550
+ with Path(path).open(encoding="utf-8", errors="replace") as fh:
551
+ return [v for line in fh if (v := line.strip()) and not v.startswith("#")]
552
+ except OSError: # skip a file we cannot read, the same as one that names no version
553
+ _LOGGER.debug("failed to read %s", path, exc_info=True)
554
+ return []
555
+
556
+
547
557
  class PathPythonInfo(PythonInfo):
548
558
  """python info from path."""
549
559
 
@@ -2,6 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ import copy
5
6
  import json
6
7
  import logging
7
8
  import os
@@ -475,7 +476,10 @@ class PythonInfo: # ruff:ignore[too-many-public-methods]
475
476
  resolved = cls.from_exe(target.system_executable, cache)
476
477
  if resolved is not None:
477
478
  target = resolved
478
- target.executable = start_executable
479
+ if target.executable != start_executable:
480
+ # the cache hands every lookup of this base the same object, so point a copy at the start executable
481
+ target = copy.copy(target)
482
+ target.executable = start_executable
479
483
  return target
480
484
 
481
485
  _cache_exe_discovery: ClassVar[dict[tuple[str, bool], PythonInfo]] = {}
@@ -10,26 +10,29 @@ from typing import Final
10
10
  from ._py_info import normalize_isa
11
11
  from ._specifier import SimpleSpecifier, SimpleSpecifierSet, SimpleVersion
12
12
 
13
- PATTERN = re.compile(
14
- r"""
15
- ^
16
- (?P<impl>[a-zA-Z]+)? # implementation (e.g. cpython, pypy)
17
- (?P<version>[0-9.]+)? # version (e.g. 3.12, 3.12.1)
13
+ _MODIFIERS: Final[str] = r"""
18
14
  (?P<threaded>t)? # free-threaded flag
19
15
  (?P<debug>d|(?:-dbg|-debug)(?=-|$))? # debug build flag (d, -dbg or -debug)
20
16
  (?:-(?P<arch>32|64))? # architecture bitness
21
17
  (?:-(?P<machine>[a-zA-Z0-9_.]+))? # ISA (e.g. arm64, x86_64, i86pc.64bit)
22
18
  $
23
- """,
19
+ """
20
+ PATTERN = re.compile(
21
+ r"""
22
+ ^
23
+ (?P<impl>[a-zA-Z]+)? # implementation (e.g. cpython, pypy)
24
+ (?P<version>[0-9.]+)? # version (e.g. 3.12, 3.12.1)
25
+ """
26
+ + _MODIFIERS,
24
27
  re.VERBOSE,
25
28
  )
26
29
  SPECIFIER_PATTERN = re.compile(
27
30
  r"""
28
31
  ^
29
32
  (?:(?P<impl>[A-Za-z]+)\s*)? # optional implementation prefix
30
- (?P<spec>(?:===|==|~=|!=|<=|>=|<|>).+) # PEP 440 version specifier
31
- $
32
- """,
33
+ (?P<spec>(?:===|==|~=|!=|<=|>=|<|>).*?) # PEP 440 version specifier, lazy so the modifiers can follow it
34
+ """
35
+ + _MODIFIERS,
33
36
  re.VERBOSE,
34
37
  )
35
38
 
@@ -69,51 +72,60 @@ def _parse_version_parts(version: str) -> tuple[int | None, int | None, int | No
69
72
  def _parse_spec_pattern(string_spec: str) -> PythonSpec | None:
70
73
  if not (match := re.match(PATTERN, string_spec)):
71
74
  return None
72
- groups = match.groupdict()
73
- version = groups["version"]
74
- major, minor, micro, threaded = None, None, None, None
75
- debug = True if groups["debug"] else None # unconstrained unless an explicit d/-dbg/-debug marker is present
76
- if version is not None:
75
+ release, threaded = (None, None, None), None
76
+ if (version := match["version"]) is not None:
77
77
  try:
78
- major, minor, micro = _parse_version_parts(version)
78
+ release = _parse_version_parts(version)
79
79
  except ValueError:
80
80
  return None
81
- threaded = bool(groups["threaded"])
82
- impl = groups["impl"]
81
+ threaded = bool(match["threaded"])
82
+ return _spec_from_match(string_spec, match, release, threaded=threaded, version_specifier=None)
83
+
84
+
85
+ def _spec_from_match(
86
+ string_spec: str,
87
+ match: re.Match[str],
88
+ release: tuple[int | None, int | None, int | None],
89
+ *,
90
+ threaded: bool | None,
91
+ version_specifier: SpecifierSet | None,
92
+ ) -> PythonSpec:
93
+ impl = match["impl"]
83
94
  if impl in {"py", "python"}:
84
95
  impl = None
85
96
  if impl == "graalvm":
86
97
  impl = "graalpy"
87
- arch = _int_or_none(groups["arch"])
88
- machine = groups.get("machine")
89
- if machine is not None:
90
- machine = normalize_isa(machine)
91
98
  return PythonSpec(
92
- string_spec, impl, major, minor, micro, arch, None, free_threaded=threaded, machine=machine, debug=debug
99
+ string_spec,
100
+ impl,
101
+ *release,
102
+ _int_or_none(match["arch"]),
103
+ None,
104
+ free_threaded=threaded,
105
+ machine=None if (machine := match["machine"]) is None else normalize_isa(machine),
106
+ debug=True if match["debug"] else None, # unconstrained unless an explicit d/-dbg/-debug marker is present
107
+ version_specifier=version_specifier,
93
108
  )
94
109
 
95
110
 
96
111
  def _parse_specifier(string_spec: str) -> PythonSpec | None:
97
- if not (specifier_match := SPECIFIER_PATTERN.match(string_spec.strip())):
98
- return None
99
- if SpecifierSet is None: # pragma: no cover
112
+ if not (match := SPECIFIER_PATTERN.match(string_spec.strip())):
100
113
  return None
101
- impl = specifier_match.group("impl")
102
- spec_text = specifier_match.group("spec").strip()
103
- try:
104
- version_specifier = SpecifierSet.from_string(spec_text)
105
- except InvalidSpecifier: # pragma: no cover
106
- return None
107
- # the set never raises: it keeps an unparsable version as None and drops items without an operator, so fall back
108
- # to a literal path, like any other unrecognized spec, unless every item parsed into a usable version
114
+ spec_text = match["spec"].strip()
115
+ version_specifier = SpecifierSet.from_string(spec_text)
116
+ # the set never raises: it keeps an unparsable version as None and drops items without an operator
109
117
  items = [item for item in spec_text.split(",") if item.strip()]
110
118
  if len(items) != len(version_specifier.specifiers) or any(spec.version is None for spec in version_specifier):
111
- return None
112
- if impl in {"py", "python"}:
113
- impl = None
114
- if impl == "graalvm":
115
- impl = "graalpy"
116
- return PythonSpec(string_spec, impl, None, None, None, None, None, version_specifier=version_specifier)
119
+ msg = f"invalid version specifier {string_spec!r}"
120
+ raise ValueError(msg)
121
+ return _spec_from_match(
122
+ string_spec,
123
+ match,
124
+ (None, None, None),
125
+ # the version bounds say nothing about the build, so without a trailing t any build qualifies
126
+ threaded=True if match["threaded"] else None,
127
+ version_specifier=version_specifier,
128
+ )
117
129
 
118
130
 
119
131
  class PythonSpec:
@@ -169,6 +181,7 @@ class PythonSpec:
169
181
 
170
182
  :param string_spec: an interpreter spec — an absolute path, a version string, an implementation prefix,
171
183
  or a `version specifier <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_.
184
+ :raises ValueError: if the spec starts with a version specifier operator but does not parse as one.
172
185
  """
173
186
  if pathlib.Path(string_spec).is_absolute():
174
187
  return cls(string_spec, None, None, None, None, None, string_spec)
@@ -119,7 +119,7 @@ def test_discovery_fallback_fail(session_cache: DiskCache, caplog: pytest.LogCap
119
119
  assert "accepted" not in caplog.text
120
120
 
121
121
 
122
- @pytest.mark.parametrize("missing", ["magic-one", "python.", ">=3.12 <4"])
122
+ @pytest.mark.parametrize("missing", ["magic-one", "python."])
123
123
  def test_discovery_fallback_ok(missing: str, session_cache: DiskCache, caplog: pytest.LogCaptureFixture) -> None:
124
124
  caplog.set_level(logging.DEBUG)
125
125
  result = get_interpreter([missing, sys.executable], cache=session_cache)
@@ -128,6 +128,11 @@ def test_discovery_fallback_ok(missing: str, session_cache: DiskCache, caplog: p
128
128
  assert "accepted" in caplog.text
129
129
 
130
130
 
131
+ def test_discovery_invalid_specifier_raises(session_cache: DiskCache) -> None:
132
+ with pytest.raises(ValueError, match=r"^invalid version specifier '>=3\.12 <4'$"):
133
+ get_interpreter([">=3.12 <4", sys.executable], cache=session_cache)
134
+
135
+
131
136
  @pytest.fixture
132
137
  def mock_find_interpreter(mocker: MockerFixture) -> None:
133
138
  mocker.patch(
@@ -167,6 +172,18 @@ def test_discovery_absolute_path_with_try_first(
167
172
  assert Path(interpreter.executable) == good_exe
168
173
 
169
174
 
175
+ def test_discovery_venvs_on_one_base_keep_their_executable(tmp_path: Path, session_cache: DiskCache) -> None:
176
+ scripts_dir = "Scripts" if IS_WIN else "bin"
177
+ exe_name = "python.exe" if IS_WIN else "python"
178
+ exes = [tmp_path / name / scripts_dir / exe_name for name in ("a", "b")]
179
+ for exe in exes:
180
+ subprocess.check_call([sys.executable, "-m", "venv", "--without-pip", str(exe.parents[1])])
181
+
182
+ found = [get_interpreter(str(exe), cache=session_cache) for exe in exes]
183
+
184
+ assert [Path(info.executable) for info in found if info is not None] == exes
185
+
186
+
170
187
  def test_discovery_via_path_with_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
171
188
  a_file = tmp_path / "a_file"
172
189
  a_file.touch()
@@ -248,6 +265,11 @@ def test_discovery_via_version_specifier(session_cache: DiskCache) -> None:
248
265
  assert interpreter.implementation == "CPython"
249
266
 
250
267
 
268
+ _POSIX_PERMISSIONS: Final[pytest.MarkDecorator] = pytest.mark.skipif(
269
+ IS_WIN or os.geteuid() == 0, reason="POSIX file permissions, which root bypasses"
270
+ )
271
+
272
+
251
273
  def _create_version_manager(tmp_path: Path, env_var: str) -> Path:
252
274
  root = tmp_path / env_var.lower()
253
275
  root.mkdir()
@@ -346,6 +368,61 @@ def test_shim_uses_python_version_file(tmp_path: Path, monkeypatch: pytest.Monke
346
368
  assert mock_from_exe.call_args_list[0][0][0] == str(real_binary)
347
369
 
348
370
 
371
+ def test_shim_python_version_file_not_utf8(
372
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, pyenv_probed: Callable[[], tuple[str, ...]]
373
+ ) -> None:
374
+ (tmp_path / ".python-version").write_bytes(b"# pinned by M\xfcller\n2.7.18\n")
375
+ monkeypatch.chdir(tmp_path)
376
+
377
+ assert pyenv_probed() == ("versions", "2.7.18")
378
+
379
+
380
+ @_POSIX_PERMISSIONS
381
+ def test_shim_unreadable_python_version_file_is_skipped(
382
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, pyenv_probed: Callable[[], tuple[str, ...]]
383
+ ) -> None:
384
+ (tmp_path / ".python-version").write_text("2.7.18\n", encoding="utf-8")
385
+ (unreadable := tmp_path / "child" / ".python-version").parent.mkdir()
386
+ unreadable.write_text("3.12.0\n", encoding="utf-8")
387
+ unreadable.chmod(0)
388
+ monkeypatch.chdir(unreadable.parent)
389
+
390
+ assert pyenv_probed() == ("versions", "2.7.18")
391
+
392
+
393
+ @_POSIX_PERMISSIONS
394
+ def test_shim_unsearchable_directory_is_skipped(
395
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, pyenv_probed: Callable[[], tuple[str, ...]]
396
+ ) -> None:
397
+ (tmp_path / ".python-version").write_text("2.7.18\n", encoding="utf-8")
398
+ (work := tmp_path / "locked" / "work").mkdir(parents=True)
399
+ monkeypatch.chdir(work)
400
+ work.parent.chmod(0o600)
401
+ try:
402
+ assert pyenv_probed() == ("versions", "2.7.18")
403
+ finally:
404
+ work.parent.chmod(0o700)
405
+
406
+
407
+ @pytest.fixture
408
+ def pyenv_probed(
409
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, mocker: MockerFixture
410
+ ) -> Callable[[], tuple[str, ...]]:
411
+ root = _create_version_manager(tmp_path, "PYENV_ROOT")
412
+ _create_versioned_binary(root, ("versions",), "2.7.18", "python2.7")
413
+ (root / "shims" / ("python2.7.exe" if IS_WIN else "python2.7")).touch(mode=0o755)
414
+ monkeypatch.setenv("PATH", str(root / "shims"))
415
+ monkeypatch.setenv("PYENV_ROOT", str(root))
416
+ monkeypatch.delenv("PYENV_VERSION", raising=False)
417
+ from_exe = mocker.patch("python_discovery._discovery.PathPythonInfo.from_exe", return_value=None)
418
+
419
+ def _probed() -> tuple[str, ...]:
420
+ get_interpreter("python2.7", [])
421
+ return Path(from_exe.call_args_list[0].args[0]).relative_to(root).parts[:2]
422
+
423
+ return _probed
424
+
425
+
349
426
  def test_shim_pyenv_version_env_takes_priority_over_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
350
427
  root = _create_version_manager(tmp_path, "PYENV_ROOT")
351
428
  _create_versioned_binary(root, ("versions",), "2.7.18", "python2.7")
@@ -431,6 +431,42 @@ def test_iter_interpreters_uv_minor_version_link_loses_to_its_target(
431
431
  assert uv_probed("3.15") == ["cpython-3.15.0b3-macos-aarch64-none/bin/python"]
432
432
 
433
433
 
434
+ @pytest.mark.parametrize(
435
+ ("concrete", "link"),
436
+ [
437
+ pytest.param("cpython-3.15.0b3-windows-x86_64-none", "cpython-3.15-windows-x86_64-none", id="prerelease"),
438
+ # the link ties with its target on version, so directory name order decides, and "-" sorts before "."
439
+ pytest.param("cpython-3.14.0-windows-x86_64-none", "cpython-3.14-windows-x86_64-none", id="first-release"),
440
+ ],
441
+ )
442
+ def test_iter_interpreters_uv_minor_version_junction_loses_to_its_target(
443
+ uv_install: Callable[..., None],
444
+ uv_probed: Callable[[str | None], list[str]],
445
+ uv_junction: Callable[[str, str], None],
446
+ concrete: str,
447
+ link: str,
448
+ ) -> None:
449
+ uv_install(f"{concrete}/python.exe")
450
+ uv_junction(concrete, link)
451
+
452
+ assert uv_probed("3") == [f"{concrete}/python.exe"]
453
+
454
+
455
+ @pytest.fixture
456
+ def uv_junction(uv_dir: Path, mocker: MockerFixture) -> Callable[[str, str], None]:
457
+ def _junction(target: str, link: str) -> None:
458
+ if IS_WIN: # pragma: win32 cover
459
+ import _winapi
460
+
461
+ _winapi.CreateJunction(str(uv_dir / target), str(uv_dir / link))
462
+ else: # pragma: win32 no cover
463
+ # stand in for the junction with a symlink that does not report as one
464
+ (uv_dir / link).symlink_to(uv_dir / target)
465
+ mocker.patch.object(Path, "is_symlink", return_value=False)
466
+
467
+ return _junction
468
+
469
+
434
470
  def test_iter_interpreters_uv_probes_one_executable_per_install(
435
471
  uv_dir: Path, uv_install: Callable[..., None], monkeypatch: pytest.MonkeyPatch, mocker: MockerFixture
436
472
  ) -> None:
@@ -195,6 +195,18 @@ def test_satisfies_version_specifier_fails() -> None:
195
195
  assert CURRENT.satisfies(spec, impl_must_match=False) is False
196
196
 
197
197
 
198
+ @pytest.mark.parametrize(
199
+ ("suffix", "expected"),
200
+ [
201
+ pytest.param("t", CURRENT.free_threaded, id="free-threaded"),
202
+ pytest.param("", True, id="any-build"),
203
+ ],
204
+ )
205
+ def test_satisfies_version_specifier_free_threaded(suffix: str, expected: bool) -> None:
206
+ spec = PythonSpec.from_string_spec(f">={sys.version_info.major}.{sys.version_info.minor}{suffix}")
207
+ assert CURRENT.satisfies(spec, impl_must_match=False) is expected
208
+
209
+
198
210
  def test_satisfies_version_specifier_unparsable_version() -> None:
199
211
  specifier = SimpleSpecifierSet.from_string(">=3.x")
200
212
  spec = PythonSpec(">=3.x", None, None, None, None, None, None, version_specifier=specifier)
@@ -439,3 +451,36 @@ def test_resolve_to_system_from_exe_returns_none(mocker: MockerFixture) -> None:
439
451
  mocker.patch.object(PythonInfo, "from_exe", return_value=None)
440
452
  result = PythonInfo.resolve_to_system(None, target)
441
453
  assert result.executable == "/some/venv/python"
454
+
455
+
456
+ @pytest.mark.parametrize(
457
+ "system_executable",
458
+ [
459
+ pytest.param("/some/system/python", id="resolved"),
460
+ pytest.param(None, id="discovered"),
461
+ ],
462
+ )
463
+ def test_resolve_to_system_leaves_shared_info_untouched(mocker: MockerFixture, system_executable: str | None) -> None:
464
+ shared = copy.deepcopy(CURRENT)
465
+ shared.system_executable = shared.executable = "/some/system/python"
466
+ mocker.patch.object(PythonInfo, "from_exe", return_value=shared)
467
+ mocker.patch.object(PythonInfo, "discover_exe", return_value=shared)
468
+
469
+ results: list[PythonInfo] = []
470
+ for venv in ("/some/venv-a", "/some/venv-b"):
471
+ target = copy.deepcopy(CURRENT)
472
+ target.system_executable = system_executable
473
+ target.real_prefix, target.base_prefix, target.executable = None, venv, f"{venv}/python"
474
+ results.append(PythonInfo.resolve_to_system(None, target))
475
+
476
+ assert [(info.executable, info.system_executable) for info in results] == [
477
+ ("/some/venv-a/python", "/some/system/python"),
478
+ ("/some/venv-b/python", "/some/system/python"),
479
+ ]
480
+ assert shared.executable == "/some/system/python"
481
+
482
+
483
+ def test_resolve_to_system_returns_target_when_executable_unchanged() -> None:
484
+ target = copy.deepcopy(CURRENT)
485
+ target.system_executable = target.executable = "/some/system/python"
486
+ assert PythonInfo.resolve_to_system(None, target) is target
@@ -1,5 +1,6 @@
1
1
  from __future__ import annotations
2
2
 
3
+ import re
3
4
  import sys
4
5
  from typing import TYPE_CHECKING
5
6
 
@@ -23,15 +24,6 @@ if TYPE_CHECKING:
23
24
  "python.",
24
25
  "cpython..",
25
26
  "pypy...",
26
- ">=3.x",
27
- ">=3.12 <4",
28
- ">=3.10.post1",
29
- "cpython>=v3.10",
30
- ">=3.12,<4.x",
31
- ">=3.x,<4",
32
- "<,4",
33
- ">=3.12,foo",
34
- ">=3.12, 4",
35
27
  ],
36
28
  )
37
29
  def test_bad_py_spec(text: str) -> None:
@@ -45,6 +37,49 @@ def test_bad_py_spec(text: str) -> None:
45
37
  assert all(v is None for v in content.values())
46
38
 
47
39
 
40
+ @pytest.mark.parametrize(
41
+ "text",
42
+ [
43
+ pytest.param(">=3.x", id="non-numeric-version"),
44
+ pytest.param(">=3.13.", id="trailing-dot"),
45
+ pytest.param(">=3.10.post1", id="post-release"),
46
+ pytest.param("cpython>=v3.10", id="v-prefix"),
47
+ pytest.param(">=3.12 <4", id="missing-comma"),
48
+ pytest.param(">=3.12,<4.x", id="bad-last-item"),
49
+ pytest.param(">=3.x,<4", id="bad-first-item"),
50
+ pytest.param("<,4", id="operator-without-version"),
51
+ pytest.param(">=3.12,foo", id="item-without-operator"),
52
+ pytest.param(">=", id="bare-operator"),
53
+ pytest.param(">=3.13t,<3.15", id="modifier-before-last-item"),
54
+ ],
55
+ )
56
+ def test_invalid_specifier_raises(text: str) -> None:
57
+ with pytest.raises(ValueError, match=f"^invalid version specifier {re.escape(repr(text))}$"):
58
+ PythonSpec.from_string_spec(text)
59
+
60
+
61
+ @pytest.mark.parametrize(
62
+ ("text", "expected"),
63
+ [
64
+ pytest.param(">=3.13t", (">=3.13", True, None, None, None), id="free-threaded"),
65
+ pytest.param(">=3.13td", (">=3.13", True, True, None, None), id="free-threaded-debug"),
66
+ pytest.param(">=3.13-dbg", (">=3.13", None, True, None, None), id="debug"),
67
+ pytest.param(">=3.11,<3.14t", (">=3.11,<3.14", True, None, None, None), id="set"),
68
+ pytest.param("cpython>=3.12-64-arm64", (">=3.12", None, None, 64, "arm64"), id="arch-machine"),
69
+ pytest.param(">=3.13", (">=3.13", None, None, None, None), id="any-build"),
70
+ ],
71
+ )
72
+ def test_specifier_modifiers(text: str, expected: tuple[str, bool | None, bool | None, int | None, str | None]) -> None:
73
+ spec = PythonSpec.from_string_spec(text)
74
+ assert (
75
+ str(spec.version_specifier),
76
+ spec.free_threaded,
77
+ spec.debug,
78
+ spec.architecture,
79
+ spec.machine,
80
+ ) == expected
81
+
82
+
48
83
  def test_py_spec_first_digit_only_major() -> None:
49
84
  spec = PythonSpec.from_string_spec("278")
50
85
  assert spec.major == 2
@@ -101,11 +101,6 @@ def test_single_digit_version() -> None:
101
101
  assert spec.minor is None
102
102
 
103
103
 
104
- def test_specifier_with_invalid_inner() -> None:
105
- spec = PythonSpec.from_string_spec(">=not_a_version")
106
- assert spec.path is None or spec.version_specifier is not None or spec.path == ">=not_a_version"
107
-
108
-
109
104
  def test_two_digit_version() -> None:
110
105
  spec = PythonSpec.from_string_spec("python312")
111
106
  assert spec.major == 3
@@ -1,9 +0,0 @@
1
- # Security Policy
2
-
3
- ## Supported Versions
4
-
5
- Only the latest released version is supported with security updates. Older versions will not receive patches.
6
-
7
- ## Reporting a Vulnerability
8
-
9
- Please report security vulnerabilities via [GitHub's private vulnerability reporting](../../security/advisories/new).