python-discovery 1.9.1__tar.gz → 1.9.4__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 (75) hide show
  1. python_discovery-1.9.4/.github/workflows/check.yaml +76 -0
  2. python_discovery-1.9.4/.github/workflows/codeql.yaml +22 -0
  3. {python_discovery-1.9.1 → python_discovery-1.9.4}/.github/workflows/news.yaml +3 -6
  4. {python_discovery-1.9.1 → python_discovery-1.9.4}/.github/workflows/prepare-release.yaml +1 -1
  5. python_discovery-1.9.4/.github/workflows/release.yaml +56 -0
  6. python_discovery-1.9.4/.github/workflows/scorecard.yaml +26 -0
  7. {python_discovery-1.9.1 → python_discovery-1.9.4}/.github/workflows/upgrade-release-tools.yaml +1 -1
  8. {python_discovery-1.9.1 → python_discovery-1.9.4}/.pre-commit-config.yaml +3 -3
  9. {python_discovery-1.9.1 → python_discovery-1.9.4}/PKG-INFO +3 -1
  10. {python_discovery-1.9.1 → python_discovery-1.9.4}/README.md +2 -0
  11. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/changelog.rst +97 -0
  12. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/explanation.rst +57 -15
  13. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/how-to/standalone-usage.rst +3 -0
  14. {python_discovery-1.9.1 → python_discovery-1.9.4}/pylock.toml +160 -161
  15. {python_discovery-1.9.1 → python_discovery-1.9.4}/pyproject.toml +5 -5
  16. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_cache.py +86 -14
  17. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_cached_py_info.py +175 -49
  18. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_discovery.py +55 -27
  19. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_py_info.py +22 -11
  20. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_py_info_collect.py +12 -4
  21. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_specifier.py +8 -0
  22. python_discovery-1.9.4/src/python_discovery/_windows/_cancel_io.py +51 -0
  23. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_windows/_pep514.py +10 -5
  24. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/py_info/test_py_info.py +9 -3
  25. python_discovery-1.9.4/tests/test_cache.py +381 -0
  26. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_cached_py_info.py +223 -22
  27. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_discovery.py +411 -15
  28. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_py_info_collect.py +65 -4
  29. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_py_info_extra.py +92 -3
  30. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_query_timeout.py +27 -5
  31. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_specifier.py +5 -0
  32. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/windows/test_windows.py +13 -1
  33. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/windows/test_windows_pep514.py +35 -1
  34. python_discovery-1.9.1/.github/workflows/check.yaml +0 -99
  35. python_discovery-1.9.1/.github/workflows/codeql.yaml +0 -41
  36. python_discovery-1.9.1/.github/workflows/release.yaml +0 -117
  37. python_discovery-1.9.1/tests/test_cache.py +0 -115
  38. {python_discovery-1.9.1 → python_discovery-1.9.4}/.github/FUNDING.yaml +0 -0
  39. {python_discovery-1.9.1 → python_discovery-1.9.4}/.github/SECURITY.md +0 -0
  40. {python_discovery-1.9.1 → python_discovery-1.9.4}/.github/THREAT_MODEL.md +0 -0
  41. {python_discovery-1.9.1 → python_discovery-1.9.4}/.github/dependabot.yaml +0 -0
  42. {python_discovery-1.9.1 → python_discovery-1.9.4}/.github/release.yaml +0 -0
  43. {python_discovery-1.9.1 → python_discovery-1.9.4}/.gitignore +0 -0
  44. {python_discovery-1.9.1 → python_discovery-1.9.4}/.readthedocs.yaml +0 -0
  45. {python_discovery-1.9.1 → python_discovery-1.9.4}/.readthedocs.yml +0 -0
  46. {python_discovery-1.9.1 → python_discovery-1.9.4}/CODE_OF_CONDUCT.md +0 -0
  47. {python_discovery-1.9.1 → python_discovery-1.9.4}/LICENSE +0 -0
  48. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/_static/custom.css +0 -0
  49. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/_static/github.svg +0 -0
  50. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/_static/logo.svg +0 -0
  51. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/changelog/template.jinja2 +0 -0
  52. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/conf.py +0 -0
  53. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/contributing.rst +0 -0
  54. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/index.rst +0 -0
  55. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/reference/api.rst +0 -0
  56. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/reference/environment-variables.rst +0 -0
  57. {python_discovery-1.9.1 → python_discovery-1.9.4}/docs/tutorial/getting-started.rst +0 -0
  58. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/__init__.py +0 -0
  59. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_compat.py +0 -0
  60. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_py_spec.py +0 -0
  61. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_windows/__init__.py +0 -0
  62. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/_windows/_propose.py +0 -0
  63. {python_discovery-1.9.1 → python_discovery-1.9.4}/src/python_discovery/py.typed +0 -0
  64. {python_discovery-1.9.1 → python_discovery-1.9.4}/tasks/old_target_check.py +0 -0
  65. {python_discovery-1.9.1 → python_discovery-1.9.4}/tasks/old_target_check.sh +0 -0
  66. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/conftest.py +0 -0
  67. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/py_info/test_py_info_exe_based_of.py +0 -0
  68. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_cache_recovery.py +0 -0
  69. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_discovery_extra.py +0 -0
  70. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_iter_interpreters.py +0 -0
  71. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_py_spec.py +0 -0
  72. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/test_py_spec_extra.py +0 -0
  73. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/windows/conftest.py +0 -0
  74. {python_discovery-1.9.1 → python_discovery-1.9.4}/tests/windows/winreg_mock_values.py +0 -0
  75. {python_discovery-1.9.1 → python_discovery-1.9.4}/tox.toml +0 -0
@@ -0,0 +1,76 @@
1
+ name: 🧪 check
2
+ on:
3
+ workflow_dispatch:
4
+ push:
5
+ branches: ["main"]
6
+ tags-ignore: ["**"]
7
+ pull_request:
8
+ types: [opened, synchronize, reopened]
9
+ schedule:
10
+ - cron: "0 8 * * *"
11
+ concurrency:
12
+ group: check-${{ github.ref }}
13
+ cancel-in-progress: true
14
+ permissions:
15
+ contents: read
16
+ jobs:
17
+ test:
18
+ name: 🧪 Test
19
+ uses: tox-dev/github-workflows/.github/workflows/check.yaml@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
20
+ permissions:
21
+ contents: read
22
+ with:
23
+ include: |
24
+ [
25
+ {"env": "3.15"},
26
+ {"env": "3.15t", "python": "3.15t"},
27
+ {"env": "3.14", "python": "3.14"},
28
+ {"env": "3.13", "python": "3.13"},
29
+ {"env": "3.12", "python": "3.12"},
30
+ {"env": "3.11", "python": "3.11"},
31
+ {"env": "3.10", "python": "3.10"},
32
+ {"env": "3.9", "python": "3.9"},
33
+ {"env": "type-3.9"},
34
+ {"env": "type-3.15"},
35
+ {"env": "dev"},
36
+ {"env": "pkg_meta"}
37
+ ]
38
+ old-target:
39
+ name: 🧪 Test on old target
40
+ runs-on: ubuntu-26.04
41
+ steps:
42
+ - name: 📥 Check out code
43
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
44
+ with:
45
+ fetch-depth: 0
46
+ persist-credentials: false
47
+ - name: 🐍 Install uv
48
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
49
+ with:
50
+ version: latest-known
51
+ python-version: "3.15"
52
+ enable-cache: false
53
+ cache-dependency-glob: "pyproject.toml"
54
+ github-token: ${{ secrets.GITHUB_TOKEN }}
55
+ - name: 🏗️ Build the wheel
56
+ run: uv build --wheel --out-dir dist .
57
+ - parallel:
58
+ - name: 🧪 Discover Python 3.6
59
+ run: tasks/old_target_check.sh 3.6 discover
60
+ - name: 🧪 Discover Python 3.7
61
+ run: tasks/old_target_check.sh 3.7 discover
62
+ - name: 🧪 Reject Python 3.5
63
+ run: tasks/old_target_check.sh 3.5 rejected
64
+ - name: 🧪 Reject Python 2.7
65
+ run: tasks/old_target_check.sh 2.7 rejected
66
+ gate:
67
+ name: 🚦 ${{ github.event_name == 'pull_request' && 'Required checks pass' || 'Non-PR checks pass' }}
68
+ if: ${{ !cancelled() }} # codespell:ignore cancelled
69
+ needs: [test, old-target]
70
+ runs-on: ubuntu-26.04
71
+ permissions: {}
72
+ steps:
73
+ - name: 🚦 Require all needed jobs to pass
74
+ uses: tox-dev/github-workflows/required-checks@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
75
+ with:
76
+ needs: ${{ toJSON(needs) }}
@@ -0,0 +1,22 @@
1
+ name: 🛡️ CodeQL
2
+ on:
3
+ workflow_dispatch:
4
+ push:
5
+ branches: ["main"]
6
+ pull_request:
7
+ schedule:
8
+ - cron: "0 8 * * 2"
9
+ concurrency:
10
+ group: ${{ github.workflow }}-${{ github.ref }}
11
+ cancel-in-progress: true
12
+ permissions: {}
13
+ jobs:
14
+ analyze:
15
+ name: 🛡️ Analyze
16
+ uses: tox-dev/github-workflows/.github/workflows/codeql.yaml@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
17
+ permissions:
18
+ contents: read
19
+ security-events: write
20
+ with:
21
+ languages: '["actions","python"]'
22
+ paths-ignore: '["tests"]'
@@ -2,9 +2,6 @@ name: 📝 Changelog
2
2
  on:
3
3
  pull_request:
4
4
  types: [opened, reopened, synchronize, labeled, unlabeled]
5
- concurrency:
6
- group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
7
- cancel-in-progress: true
8
5
  permissions:
9
6
  contents: read
10
7
  pull-requests: read
@@ -19,15 +16,15 @@ jobs:
19
16
  fetch-depth: 0
20
17
  persist-credentials: false
21
18
  - name: 🐍 Install uv
22
- uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
19
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
23
20
  with:
24
21
  version: latest-known
25
22
  python-version: "3.15"
26
23
  enable-cache: false
27
24
  - name: 📦 Install locked release tools
28
- uses: tox-dev/github-workflows/install-locked-tools@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
25
+ uses: tox-dev/github-workflows/install-locked-tools@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
29
26
  with:
30
27
  groups: release-news
31
28
  venv: ${{ runner.temp }}/release-tools
32
29
  - name: 🔍 Validate news fragments
33
- uses: tox-dev/github-workflows/validate-news@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
30
+ uses: tox-dev/github-workflows/validate-news@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
@@ -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@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
15
+ uses: tox-dev/github-workflows/.github/workflows/prepare-towncrier-release.yaml@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
16
16
  permissions:
17
17
  contents: read
18
18
  pull-requests: read
@@ -0,0 +1,56 @@
1
+ name: 🚀 Release to PyPI
2
+ on:
3
+ push:
4
+ tags: ["*"]
5
+ permissions:
6
+ contents: read
7
+ concurrency:
8
+ group: release-${{ github.ref }}
9
+ cancel-in-progress: false
10
+ jobs:
11
+ build:
12
+ name: 🏗️ Build
13
+ uses: tox-dev/github-workflows/.github/workflows/validate-python-release.yaml@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
14
+ permissions:
15
+ contents: read
16
+ notes:
17
+ name: 📝 Render GitHub Release notes
18
+ uses: tox-dev/github-workflows/.github/workflows/release-notes.yaml@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
19
+ permissions:
20
+ contents: read
21
+ with:
22
+ tag: ${{ github.ref_name }}
23
+ changelog: docs/changelog.rst
24
+ artifact-url: https://pypi.org/project/python-discovery/${{ github.ref_name }}/
25
+ release:
26
+ name: 🚀 Publish to PyPI
27
+ needs: [build, notes]
28
+ runs-on: ubuntu-26.04
29
+ environment:
30
+ name: release
31
+ url: https://pypi.org/project/python-discovery/${{ github.ref_name }}
32
+ permissions:
33
+ id-token: write
34
+ steps:
35
+ - name: 📩 Download distributions
36
+ uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
37
+ with:
38
+ artifact-ids: ${{ needs.build.outputs.distributions-artifact-id }}
39
+ path: dist/
40
+ - name: 🚀 Publish to PyPI
41
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
42
+ with:
43
+ packages-dir: dist
44
+ github-release:
45
+ name: 🚀 Publish GitHub Release
46
+ needs: [build, notes, release]
47
+ uses: tox-dev/github-workflows/.github/workflows/github-release.yaml@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
48
+ permissions:
49
+ contents: write
50
+ with:
51
+ project: python-discovery
52
+ version: ${{ github.ref_name }}
53
+ tag: ${{ github.ref_name }}
54
+ artifact-pattern: python-package-distributions
55
+ notes-artifact-id: ${{ needs.notes.outputs.artifact-id }}
56
+ title-prefix: v
@@ -0,0 +1,26 @@
1
+ name: 🛡️ scorecard
2
+ on:
3
+ branch_protection_rule:
4
+ schedule:
5
+ - cron: "30 7 * * 2"
6
+ push:
7
+ branches: ["main"]
8
+ workflow_dispatch:
9
+ concurrency:
10
+ group: ${{ github.workflow }}-${{ github.ref }}
11
+ cancel-in-progress: true
12
+ permissions: {}
13
+ jobs:
14
+ analysis:
15
+ name: 🛡️ Scorecard analysis
16
+ if: github.repository == 'tox-dev/python-discovery'
17
+ permissions:
18
+ actions: read # read workflow runs for the Packaging check
19
+ checks: read # read check runs for the CI-Tests and SAST checks
20
+ contents: read # check out and scan the repository
21
+ id-token: write # authenticate the results published to the scorecard API
22
+ issues: read # read issue activity for the Maintained check
23
+ pull-requests: read # read reviews for the Code-Review check
24
+ security-events: write # upload the SARIF results to code scanning
25
+ statuses: read # read commit statuses for the CI-Tests check
26
+ uses: tox-dev/github-workflows/.github/workflows/scorecard.yaml@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
@@ -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@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
13
+ uses: tox-dev/github-workflows/.github/workflows/upgrade-release-tools.yaml@bceb5c005e19823dc8835f536f53f172ae223927 # 6.5.0
14
14
  permissions:
15
15
  contents: read
16
16
  secrets:
@@ -9,7 +9,7 @@ repos:
9
9
  - id: end-of-file-fixer
10
10
  - id: trailing-whitespace
11
11
  - repo: https://github.com/python-jsonschema/check-jsonschema
12
- rev: 0494aa7fa1314e98913a41227d8f0a515b2c1049 # frozen: 0.38.2
12
+ rev: a76b92851fc9eede9f9bc4073eb55202f34eb0df # frozen: 0.39.0
13
13
  hooks:
14
14
  - id: check-github-workflows
15
15
  args: ["--verbose"]
@@ -22,7 +22,7 @@ repos:
22
22
  hooks:
23
23
  - id: pyproject-fmt
24
24
  - repo: https://github.com/astral-sh/ruff-pre-commit
25
- rev: "38bfb07c0c64c304f47eb52090f8288150c77730" # frozen: v0.17.1
25
+ rev: "25bcf95026b96e2dd3c0aec3090c3d6ef6ca2e6c" # frozen: v0.17.3
26
26
  hooks:
27
27
  - id: ruff-format
28
28
  - id: ruff
@@ -57,7 +57,7 @@ repos:
57
57
  ^docs/changelog[.]rst$ # Only the generated release history.
58
58
  args: ["-l", "120", "--preserve-adornments"]
59
59
  additional_dependencies:
60
- - "sphinx==9.1.1"
60
+ - "sphinx==9.2.0"
61
61
  - repo: https://github.com/zizmorcore/zizmor-pre-commit
62
62
  rev: c92afdf2c6ca336aaa8f39e2bd8d48f62dbd8e1f # frozen: v1.31.1
63
63
  hooks:
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: python-discovery
3
- Version: 1.9.1
3
+ Version: 1.9.4
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
@@ -39,6 +39,8 @@ Description-Content-Type: text/markdown
39
39
  [![Downloads](https://static.pepy.tech/badge/python-discovery/month)](https://pepy.tech/project/python-discovery)
40
40
  [![check](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml)
41
41
  [![Documentation Status](https://readthedocs.org/projects/python-discovery/badge/?version=latest)](https://python-discovery.readthedocs.io/en/latest/?badge=latest)
42
+ [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/tox-dev/python-discovery/badge)](https://scorecard.dev/viewer/?uri=github.com/tox-dev/python-discovery)
43
+ [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/16262/badge)](https://www.bestpractices.dev/projects/16262)
42
44
 
43
45
  ## What is python-discovery?
44
46
 
@@ -5,6 +5,8 @@
5
5
  [![Downloads](https://static.pepy.tech/badge/python-discovery/month)](https://pepy.tech/project/python-discovery)
6
6
  [![check](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml)
7
7
  [![Documentation Status](https://readthedocs.org/projects/python-discovery/badge/?version=latest)](https://python-discovery.readthedocs.io/en/latest/?badge=latest)
8
+ [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/tox-dev/python-discovery/badge)](https://scorecard.dev/viewer/?uri=github.com/tox-dev/python-discovery)
9
+ [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/16262/badge)](https://www.bestpractices.dev/projects/16262)
8
10
 
9
11
  ## What is python-discovery?
10
12
 
@@ -6,6 +6,103 @@
6
6
 
7
7
  .. towncrier release notes start
8
8
 
9
+ .. _release-1-9-4:
10
+
11
+ *********************
12
+ v1.9.4 (2026-11-04)
13
+ *********************
14
+
15
+ .. _release-1-9-3:
16
+
17
+ *********************
18
+ v1.9.3 (2026-11-03)
19
+ *********************
20
+
21
+ .. _release-1-9-3-fixed:
22
+
23
+ Fixed
24
+ -----
25
+
26
+ - Reject generic Python executables when a requested implementation is unavailable (:pr:`239`) by :user:`gaborbernat`.
27
+ (:issue:`238`)
28
+
29
+ .. _release-1-9-2:
30
+
31
+ *********************
32
+ v1.9.2 (2026-11-03)
33
+ *********************
34
+
35
+ .. _release-1-9-2-fixed:
36
+
37
+ Fixed
38
+ -----
39
+
40
+ - Match literal interpreter names against the executable found on ``PATH``, including symlink names (:pr:`220`) by
41
+ :user:`gaborbernat`. (:issue:`188`)
42
+ - Preserve a virtual environment selected through ``try_first_with`` instead of returning its base interpreter
43
+ (:pr:`218`) by :user:`gaborbernat`. (:issue:`191`)
44
+ - Skip interpreter candidates that return JSON without usable interpreter metadata and continue searching (:pr:`231`) by
45
+ :user:`gaborbernat`. (:issue:`197`)
46
+ - Reject format widths in interpreter sysconfig paths before they allocate oversized strings (:pr:`229`) by
47
+ :user:`gaborbernat`. (:issue:`199`)
48
+ - Check the interpreter's reported implementation when a spec names a known implementation, regardless of its filename
49
+ on ``PATH`` (:pr:`233`) by :user:`gaborbernat`. (:issue:`201`)
50
+ - Write interpreter cache entries as compact JSON to keep their size proportional to the interpreter response
51
+ (:pr:`237`) by :user:`gaborbernat`. (:issue:`204`)
52
+ - Prevent an earlier virtual-environment lookup from reporting an executable under the wrong Python version (:pr:`215`)
53
+ by :user:`gaborbernat`.
54
+ - Retry interpreter discovery without the cache when cache access fails (:pr:`216`) by :user:`gaborbernat`.
55
+ - Exclude prereleases of the final version named by an exclusive upper bound, such as ``<3.12.0`` rejecting
56
+ ``3.12.0rc1`` (:pr:`217`) by :user:`gaborbernat`.
57
+ - Stop repeated interpreter queries when a virtual environment reports the same base prefix with different path
58
+ spellings (:pr:`219`) by :user:`gaborbernat`.
59
+ - Limit candidate stdout and stderr during interpreter queries so a noisy candidate cannot exhaust the caller's memory
60
+ (:pr:`223`) by :user:`gaborbernat`.
61
+ - Find uv-managed patch releases when a version specifier names only their major and minor version (:pr:`227`) by
62
+ :user:`gaborbernat`.
63
+ - Handle interpreter paths containing non-UTF-8 filesystem bytes when using DiskCache (:pr:`230`) by
64
+ :user:`gaborbernat`.
65
+ - Preserve interpreter-provided values when answer keys match computed properties during cache serialization (:pr:`234`)
66
+ by :user:`gaborbernat`.
67
+ - Return after an interpreter query times out without leaving pipe readers blocked by a child process (:pr:`228`) by
68
+ :user:`gaborbernat`.
69
+ - Use the supplied environment for base-interpreter probes when resolving a virtual environment (:pr:`225`) by
70
+ :user:`gaborbernat`.
71
+
72
+ .. _release-1-9-2-security:
73
+
74
+ Security
75
+ --------
76
+
77
+ - When an explicit ``env`` mapping omits ``HOME`` or ``USERPROFILE``, uv-managed interpreter discovery no longer
78
+ searches the process home directory (:pr:`236`) by :user:`gaborbernat`. (:issue:`200`)
79
+ - Skip relative ``PATH`` entries, including the working-directory entry in the Windows default search path, when
80
+ discovering interpreters (:pr:`235`) by :user:`gaborbernat`. (:issue:`202`)
81
+ - Validate pyenv, mise and asdf version names before using them as directory names. A version file can no longer direct
82
+ python-discovery's resolver to a binary outside the version manager's installation directory (:pr:`205`) by
83
+ :user:`gaborbernat`.
84
+ - When imported from an archive, python-discovery now extracts its interpreter probe into a private temporary directory.
85
+ This prevents the probe from importing modules supplied in the shared temp directory (:pr:`206`) by
86
+ :user:`gaborbernat`.
87
+ - Bare interpreter names now search ``PATH`` without probing a matching file in the working directory. Use ``./name``
88
+ when the working directory contains the intended interpreter (:pr:`207`) by :user:`gaborbernat`.
89
+ - Tcl/Tk library detection no longer executes Tk startup profile files from the home or working directory (:pr:`208`) by
90
+ :user:`gaborbernat`.
91
+ - Discovery skips ``.python-version`` files over 4096 characters during shim resolution, limiting memory use and
92
+ allowing a parent or global version to apply (:pr:`209`) by :user:`gaborbernat`.
93
+ - Discovery uses the profile default for empty or relative ``APPDATA`` and skips relative profile paths when finding
94
+ uv-managed Pythons (:pr:`210`) by :user:`gaborbernat`.
95
+ - Tcl/Tk library detection no longer opens an X display, so an unresponsive display cannot block interpreter discovery.
96
+ It can also find the Tk library on headless systems (:pr:`211`) by :user:`gaborbernat`.
97
+ - Skip PEP 514 registry entries with relative or non-string executable paths and continue interpreter discovery
98
+ (:pr:`212`) by :user:`gaborbernat`.
99
+ - Skip untrusted disk cache directories and entries on POSIX, and replace cache files without following links
100
+ (:pr:`213`) by :user:`gaborbernat`.
101
+ - Place POSIX cache locks in a restricted directory and preserve group sharing under a group-permissive umask
102
+ (:pr:`214`) by :user:`gaborbernat`.
103
+ - Interpreter discovery no longer reuses pyenv shim results across projects. A version choice in one checkout cannot
104
+ leave an unsupported-version verdict that blocks discovery in another project (:pr:`232`) by :user:`gaborbernat`.
105
+
9
106
  .. _release-1-9-1:
10
107
 
11
108
  *********************
@@ -13,9 +13,11 @@ order. It stops as soon as it finds an interpreter that matches your spec.
13
13
  Start["get_interpreter()"] --> AbsPath{"Is spec an<br>absolute path?"}
14
14
  AbsPath -->|Yes| TryAbs["Use path directly"]
15
15
  AbsPath -->|No| TryFirst["try_first_with paths"]
16
- TryFirst --> RelPath{"Is spec a<br>relative path?"}
16
+ TryFirst --> RelPath{"Does spec name a<br>relative directory?"}
17
17
  RelPath -->|Yes| TryRel["Resolve relative to cwd"]
18
- RelPath -->|No| Current["Current interpreter"]
18
+ RelPath -->|No| Bare{"Bare executable name?"}
19
+ Bare -->|Yes| PATH
20
+ Bare -->|No| Current["Current interpreter"]
19
21
  Current --> Win{"Windows?"}
20
22
  Win -->|Yes| PEP514["PEP 514 registry"]
21
23
  Win -->|No| PATH
@@ -51,19 +53,30 @@ detects these shims and resolves them to the actual binary.
51
53
 
52
54
  flowchart TD
53
55
  Shim["Shim detected"] --> EnvVar{"PYENV_VERSION<br>set?"}
54
- EnvVar -->|Yes| Use["Use that version"]
56
+ EnvVar -->|Yes| Valid{"Valid directory name?"}
55
57
  EnvVar -->|No| File{".python-version<br>names a version?"}
56
- File -->|Yes| Use
58
+ File -->|Yes| Valid
57
59
  File -->|No| Global{"pyenv global<br>version exists?"}
58
- Global -->|Yes| Use
60
+ Global -->|Yes| Valid
59
61
  Global -->|No| Skip["Skip shim"]
62
+ Valid -->|Yes| Use["Use that version"]
63
+ Valid -->|No| More{"Another version?"}
64
+ More -->|Yes| Valid
65
+ More -->|No| Skip
60
66
 
61
67
  style Shim fill:#4a90d9,stroke:#2a5f8f,color:#fff
68
+ style Valid fill:#4a90d9,stroke:#2a5f8f,color:#fff
69
+ style More fill:#4a90d9,stroke:#2a5f8f,color:#fff
62
70
  style Use fill:#4a9f4a,stroke:#2a6f2a,color:#fff
63
71
  style Skip fill:#d94a4a,stroke:#8f2a2a,color:#fff
64
72
 
65
73
  `mise <https://mise.jdx.dev/>`_ and `asdf <https://asdf-vm.com/>`_ work similarly, using the
66
74
  ``MISE_DATA_DIR`` and ``ASDF_DATA_DIR`` environment variables to locate their installations.
75
+ python-discovery skips version files over 4096 characters. It checks parent directories and, for pyenv, the global
76
+ version when needed.
77
+
78
+ A version must name one directory below the version manager's installation root. Discovery skips ``.`` and ``..`` and
79
+ version names containing a path separator, then tries the next configured version.
67
80
 
68
81
  How uv-managed Pythons are discovered
69
82
  ---------------------------------------
@@ -91,8 +104,11 @@ overrides it; otherwise the store is the ``python`` bucket of uv's state directo
91
104
  uv follows the XDG convention on macOS too, and falls back to the legacy directory only when that directory already
92
105
  exists. python-discovery searches both, in the same order, so a leftover legacy directory cannot hide the store uv
93
106
  installs into. A relative ``XDG_DATA_HOME`` does not count, as the XDG specification requires, and Windows ignores it
94
- outright. Every one of these variables comes from the ``env`` mapping passed to
95
- :func:`~python_discovery.get_interpreter`, rather than from the process environment.
107
+ outright. An empty or relative ``APPDATA`` uses the profile default when ``USERPROFILE`` is present. Discovery skips
108
+ relative store roots. Every one of these variables comes from the ``env`` mapping passed to
109
+ :func:`~python_discovery.get_interpreter`, rather than from the process environment. If the mapping omits ``HOME`` or
110
+ ``USERPROFILE``, discovery skips the corresponding home-derived roots but still searches an absolute mapped ``APPDATA``
111
+ or ``XDG_DATA_HOME``.
96
112
 
97
113
  Each install lives in its own subdirectory, but the actual binary location varies by OS and implementation:
98
114
 
@@ -236,8 +252,10 @@ links back to its own interpreter. Reading the raw field still tells the two sta
236
252
  How caching works
237
253
  -------------------
238
254
 
239
- Querying an interpreter requires a subprocess call, which is slow. The cache avoids repeating this
240
- work by storing the result as a JSON file keyed by the interpreter's path.
255
+ Querying an interpreter requires a subprocess call, which is slow. The cache stores the result as a
256
+ JSON file keyed by the queried path when that path identifies the interpreter that answered. Launchers
257
+ such as pyenv shims can select different interpreters in different directories, so their results are
258
+ not cached under the launcher path.
241
259
 
242
260
  .. mermaid::
243
261
 
@@ -245,19 +263,38 @@ work by storing the result as a JSON file keyed by the interpreter's path.
245
263
  Lookup["py_info(path)"] --> Exists{"Cache hit?"}
246
264
  Exists -->|Yes| Read["Read JSON"]
247
265
  Exists -->|No| Run["Run subprocess"]
248
- Run --> Write["Write JSON<br>(with filelock)"]
249
- Write --> Return["Return PythonInfo"]
266
+ Run --> Same{"Queried path is<br>the interpreter?"}
267
+ Same -->|Yes| Write["Write JSON<br>(with filelock)"]
268
+ Same -->|No| Return["Return query result"]
269
+ Write --> Return
250
270
  Read --> Return
251
271
 
252
272
  style Lookup fill:#4a90d9,stroke:#2a5f8f,color:#fff
253
273
  style Return fill:#4a9f4a,stroke:#2a6f2a,color:#fff
254
274
  style Run fill:#d9904a,stroke:#8f5f2a,color:#fff
275
+ style Same fill:#d9904a,stroke:#8f5f2a,color:#fff
255
276
 
256
277
  The built-in :class:`~python_discovery.DiskCache` stores files under ``<root>/py_info/4/<sha256>.json``
257
278
  with `filelock <https://py-filelock.readthedocs.io/>`_-based locking for safe concurrent access. You
258
279
  can also pass ``cache=None`` to disable caching, or implement your own backend (see
259
280
  :doc:`/how-to/standalone-usage`).
260
281
 
282
+ If cache access raises an OS error, discovery retries the interpreter query without that cache. A failed cache write
283
+ can therefore cause a second query.
284
+
285
+ On POSIX, ``DiskCache`` uses a cache root only when it and both ``py_info`` directories are real directories owned by
286
+ the current user or root and cannot be written by other users. Its ancestor directories must also prevent other users
287
+ from replacing the cache root; a sticky shared ancestor such as ``/tmp`` is allowed. Discovery continues without disk
288
+ caching and logs a warning if the directory check fails. Cache entries must be regular files owned by the current user
289
+ or root and not writable by others. Discovery tries to remove a rejected entry and queries the interpreter again. Use a
290
+ private directory for the cache root, including when callers share a machine.
291
+
292
+ A relative cache root refers to the current directory when ``DiskCache`` is created.
293
+
294
+ On POSIX, lock files live in a restricted directory under the checked cache directory. Older releases use the previous
295
+ lock files, so processes running different releases do not coordinate cache writes. Use separate cache roots while both
296
+ run.
297
+
261
298
  Subprocess timeout behavior
262
299
  ----------------------------
263
300
 
@@ -279,15 +316,19 @@ legitimate interpreters may be skipped; if too high, the discovery process may t
279
316
  when encountering problematic interpreters. For invalid values, python-discovery logs a warning and uses
280
317
  the default of 15 seconds. Set ``inf`` to disable the timeout.
281
318
 
319
+ Discovery skips a candidate that produces more than 1,048,576 characters on either stdout or stderr, even when the
320
+ timeout is disabled.
321
+
282
322
  Supported Python versions
283
323
  -------------------------
284
324
 
285
325
  Two floors apply: python-discovery itself runs on Python 3.9+ (``requires-python``), while discovery
286
326
  reaches down to Python 3.6 - old enough to cover RHEL 8's system Python.
287
327
 
288
- python-discovery skips candidates below 3.6 with one warning naming the executable, the version
289
- found, and the floor; the verdict is cached, so the interpreter is not queried again. Candidates too
290
- old to run the version check at all (before Python 2.7) fail as a generic query error. An
328
+ python-discovery skips candidates below 3.6 with a warning naming the executable, the version
329
+ found, and the floor. The verdict is cached when the candidate itself is the interpreter; launchers
330
+ such as pyenv shims are queried again because their target can depend on the current directory.
331
+ Candidates too old to run the version check at all (before Python 2.7) fail as a generic query error. An
291
332
  absolute-path spec for a below-floor interpreter raises :class:`RuntimeError` with the same message.
292
333
  The floor moves only in a major release.
293
334
 
@@ -329,7 +370,8 @@ A spec string follows the pattern ``[impl][version][t][d][-arch][-machine]``. Ev
329
370
  Order matters: the parts appear in the sequence shown above. Combine the ABI flags as ``python3.13td``
330
371
  (free-threaded then debug, the order CPython uses in ``sys.abiflags``), and keep ``-arch`` before
331
372
  ``-machine`` as in ``python3.13d-64-arm64``. Mixing ``d`` with ``-dbg`` in one spec, or swapping the arch
332
- and machine segments, leaves the string unrecognized, so it falls back to a literal executable-name match.
373
+ and machine segments, leaves the string unrecognized, so it falls back to a literal executable-name match on ``PATH``.
374
+ Only a spec with a directory component, such as ``./python3`` or ``venv/bin/python``, searches the working directory.
333
375
 
334
376
  **Full examples:**
335
377
 
@@ -61,6 +61,9 @@ shell. You can override these to control exactly where the library looks.
61
61
  env = {**os.environ, "PATH": "/usr/local/bin:/usr/bin"}
62
62
  result = get_interpreter("python3.12", env=env)
63
63
 
64
+ Only absolute directories in ``PATH`` are searched. To select an interpreter in the working directory, use
65
+ ``./python`` as the spec on POSIX or ``./python.exe`` on Windows.
66
+
64
67
  Customize interpreter query timeout
65
68
  -------------------------------------
66
69