python-discovery 1.9.1__tar.gz → 1.9.2__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 (72) hide show
  1. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/news.yaml +2 -5
  2. python_discovery-1.9.2/.github/workflows/scorecard.yaml +26 -0
  3. {python_discovery-1.9.1 → python_discovery-1.9.2}/PKG-INFO +3 -1
  4. {python_discovery-1.9.1 → python_discovery-1.9.2}/README.md +2 -0
  5. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/changelog.rst +77 -0
  6. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/explanation.rst +57 -15
  7. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/how-to/standalone-usage.rst +3 -0
  8. {python_discovery-1.9.1 → python_discovery-1.9.2}/pylock.toml +12 -14
  9. {python_discovery-1.9.1 → python_discovery-1.9.2}/pyproject.toml +5 -5
  10. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_cache.py +86 -14
  11. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_cached_py_info.py +175 -49
  12. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_discovery.py +55 -27
  13. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_py_info.py +22 -11
  14. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_py_info_collect.py +12 -4
  15. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_specifier.py +8 -0
  16. python_discovery-1.9.2/src/python_discovery/_windows/_cancel_io.py +51 -0
  17. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_windows/_pep514.py +10 -5
  18. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/py_info/test_py_info.py +9 -3
  19. python_discovery-1.9.2/tests/test_cache.py +381 -0
  20. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_cached_py_info.py +223 -22
  21. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_discovery.py +404 -15
  22. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_py_info_collect.py +65 -4
  23. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_py_info_extra.py +92 -3
  24. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_query_timeout.py +27 -5
  25. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_specifier.py +5 -0
  26. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/windows/test_windows.py +13 -1
  27. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/windows/test_windows_pep514.py +35 -1
  28. python_discovery-1.9.1/tests/test_cache.py +0 -115
  29. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/FUNDING.yaml +0 -0
  30. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/SECURITY.md +0 -0
  31. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/THREAT_MODEL.md +0 -0
  32. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/dependabot.yaml +0 -0
  33. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/release.yaml +0 -0
  34. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/check.yaml +0 -0
  35. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/codeql.yaml +0 -0
  36. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/prepare-release.yaml +0 -0
  37. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/release.yaml +0 -0
  38. {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/upgrade-release-tools.yaml +0 -0
  39. {python_discovery-1.9.1 → python_discovery-1.9.2}/.gitignore +0 -0
  40. {python_discovery-1.9.1 → python_discovery-1.9.2}/.pre-commit-config.yaml +0 -0
  41. {python_discovery-1.9.1 → python_discovery-1.9.2}/.readthedocs.yaml +0 -0
  42. {python_discovery-1.9.1 → python_discovery-1.9.2}/.readthedocs.yml +0 -0
  43. {python_discovery-1.9.1 → python_discovery-1.9.2}/CODE_OF_CONDUCT.md +0 -0
  44. {python_discovery-1.9.1 → python_discovery-1.9.2}/LICENSE +0 -0
  45. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/_static/custom.css +0 -0
  46. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/_static/github.svg +0 -0
  47. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/_static/logo.svg +0 -0
  48. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/changelog/template.jinja2 +0 -0
  49. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/conf.py +0 -0
  50. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/contributing.rst +0 -0
  51. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/index.rst +0 -0
  52. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/reference/api.rst +0 -0
  53. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/reference/environment-variables.rst +0 -0
  54. {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/tutorial/getting-started.rst +0 -0
  55. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/__init__.py +0 -0
  56. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_compat.py +0 -0
  57. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_py_spec.py +0 -0
  58. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_windows/__init__.py +0 -0
  59. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_windows/_propose.py +0 -0
  60. {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/py.typed +0 -0
  61. {python_discovery-1.9.1 → python_discovery-1.9.2}/tasks/old_target_check.py +0 -0
  62. {python_discovery-1.9.1 → python_discovery-1.9.2}/tasks/old_target_check.sh +0 -0
  63. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/conftest.py +0 -0
  64. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/py_info/test_py_info_exe_based_of.py +0 -0
  65. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_cache_recovery.py +0 -0
  66. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_discovery_extra.py +0 -0
  67. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_iter_interpreters.py +0 -0
  68. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_py_spec.py +0 -0
  69. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_py_spec_extra.py +0 -0
  70. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/windows/conftest.py +0 -0
  71. {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/windows/winreg_mock_values.py +0 -0
  72. {python_discovery-1.9.1 → python_discovery-1.9.2}/tox.toml +0 -0
@@ -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
@@ -25,9 +22,9 @@ jobs:
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@99024bcb5749b178c5514f86acfcf1e80c865e75 # 6.3.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@99024bcb5749b178c5514f86acfcf1e80c865e75 # 6.3.0
@@ -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@cfb6d637a10b70da576575790eb3c806f57cd0b5
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: python-discovery
3
- Version: 1.9.1
3
+ Version: 1.9.2
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,83 @@
6
6
 
7
7
  .. towncrier release notes start
8
8
 
9
+ .. _release-1-9-2:
10
+
11
+ *********************
12
+ v1.9.2 (2026-11-03)
13
+ *********************
14
+
15
+ .. _release-1-9-2-fixed:
16
+
17
+ Fixed
18
+ -----
19
+
20
+ - Match literal interpreter names against the executable found on ``PATH``, including symlink names (:pr:`220`) by
21
+ :user:`gaborbernat`. (:issue:`188`)
22
+ - Preserve a virtual environment selected through ``try_first_with`` instead of returning its base interpreter
23
+ (:pr:`218`) by :user:`gaborbernat`. (:issue:`191`)
24
+ - Skip interpreter candidates that return JSON without usable interpreter metadata and continue searching (:pr:`231`) by
25
+ :user:`gaborbernat`. (:issue:`197`)
26
+ - Reject format widths in interpreter sysconfig paths before they allocate oversized strings (:pr:`229`) by
27
+ :user:`gaborbernat`. (:issue:`199`)
28
+ - Check the interpreter's reported implementation when a spec names a known implementation, regardless of its filename
29
+ on ``PATH`` (:pr:`233`) by :user:`gaborbernat`. (:issue:`201`)
30
+ - Write interpreter cache entries as compact JSON to keep their size proportional to the interpreter response
31
+ (:pr:`237`) by :user:`gaborbernat`. (:issue:`204`)
32
+ - Prevent an earlier virtual-environment lookup from reporting an executable under the wrong Python version (:pr:`215`)
33
+ by :user:`gaborbernat`.
34
+ - Retry interpreter discovery without the cache when cache access fails (:pr:`216`) by :user:`gaborbernat`.
35
+ - Exclude prereleases of the final version named by an exclusive upper bound, such as ``<3.12.0`` rejecting
36
+ ``3.12.0rc1`` (:pr:`217`) by :user:`gaborbernat`.
37
+ - Stop repeated interpreter queries when a virtual environment reports the same base prefix with different path
38
+ spellings (:pr:`219`) by :user:`gaborbernat`.
39
+ - Limit candidate stdout and stderr during interpreter queries so a noisy candidate cannot exhaust the caller's memory
40
+ (:pr:`223`) by :user:`gaborbernat`.
41
+ - Find uv-managed patch releases when a version specifier names only their major and minor version (:pr:`227`) by
42
+ :user:`gaborbernat`.
43
+ - Handle interpreter paths containing non-UTF-8 filesystem bytes when using DiskCache (:pr:`230`) by
44
+ :user:`gaborbernat`.
45
+ - Preserve interpreter-provided values when answer keys match computed properties during cache serialization (:pr:`234`)
46
+ by :user:`gaborbernat`.
47
+ - Return after an interpreter query times out without leaving pipe readers blocked by a child process (:pr:`228`) by
48
+ :user:`gaborbernat`.
49
+ - Use the supplied environment for base-interpreter probes when resolving a virtual environment (:pr:`225`) by
50
+ :user:`gaborbernat`.
51
+
52
+ .. _release-1-9-2-security:
53
+
54
+ Security
55
+ --------
56
+
57
+ - When an explicit ``env`` mapping omits ``HOME`` or ``USERPROFILE``, uv-managed interpreter discovery no longer
58
+ searches the process home directory (:pr:`236`) by :user:`gaborbernat`. (:issue:`200`)
59
+ - Skip relative ``PATH`` entries, including the working-directory entry in the Windows default search path, when
60
+ discovering interpreters (:pr:`235`) by :user:`gaborbernat`. (:issue:`202`)
61
+ - Validate pyenv, mise and asdf version names before using them as directory names. A version file can no longer direct
62
+ python-discovery's resolver to a binary outside the version manager's installation directory (:pr:`205`) by
63
+ :user:`gaborbernat`.
64
+ - When imported from an archive, python-discovery now extracts its interpreter probe into a private temporary directory.
65
+ This prevents the probe from importing modules supplied in the shared temp directory (:pr:`206`) by
66
+ :user:`gaborbernat`.
67
+ - Bare interpreter names now search ``PATH`` without probing a matching file in the working directory. Use ``./name``
68
+ when the working directory contains the intended interpreter (:pr:`207`) by :user:`gaborbernat`.
69
+ - Tcl/Tk library detection no longer executes Tk startup profile files from the home or working directory (:pr:`208`) by
70
+ :user:`gaborbernat`.
71
+ - Discovery skips ``.python-version`` files over 4096 characters during shim resolution, limiting memory use and
72
+ allowing a parent or global version to apply (:pr:`209`) by :user:`gaborbernat`.
73
+ - Discovery uses the profile default for empty or relative ``APPDATA`` and skips relative profile paths when finding
74
+ uv-managed Pythons (:pr:`210`) by :user:`gaborbernat`.
75
+ - Tcl/Tk library detection no longer opens an X display, so an unresponsive display cannot block interpreter discovery.
76
+ It can also find the Tk library on headless systems (:pr:`211`) by :user:`gaborbernat`.
77
+ - Skip PEP 514 registry entries with relative or non-string executable paths and continue interpreter discovery
78
+ (:pr:`212`) by :user:`gaborbernat`.
79
+ - Skip untrusted disk cache directories and entries on POSIX, and replace cache files without following links
80
+ (:pr:`213`) by :user:`gaborbernat`.
81
+ - Place POSIX cache locks in a restricted directory and preserve group sharing under a group-permissive umask
82
+ (:pr:`214`) by :user:`gaborbernat`.
83
+ - Interpreter discovery no longer reuses pyenv shim results across projects. A version choice in one checkout cannot
84
+ leave an unsupported-version verdict that blocks discovery in another project (:pr:`232`) by :user:`gaborbernat`.
85
+
9
86
  .. _release-1-9-1:
10
87
 
11
88
  *********************
@@ -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
 
@@ -1450,7 +1450,7 @@ sha256 = "1b82aa4b37137248bd687055e109723debeb07b489de1565297dc9589c5f2d6b"
1450
1450
  [[packages]]
1451
1451
  name = "pyyaml"
1452
1452
  version = "6.0.3"
1453
- marker = "\"docs\" in dependency_groups or \"release-news\" in dependency_groups or \"release-notes\" in dependency_groups or \"release-prepare\" in dependency_groups"
1453
+ marker = "\"docs\" in dependency_groups"
1454
1454
  requires-python = ">=3.8"
1455
1455
  index = "https://pypi.org/simple/"
1456
1456
 
@@ -1495,7 +1495,7 @@ sha256 = "d0dae1f74bb273b534770cb4cccb6bb78735540afdb03c2146f4e19dcd412560"
1495
1495
 
1496
1496
  [[packages]]
1497
1497
  name = "release-creator"
1498
- version = "4.1.0"
1498
+ version = "4.4.0"
1499
1499
  marker = "\"release-news\" in dependency_groups or \"release-notes\" in dependency_groups or \"release-prepare\" in dependency_groups"
1500
1500
  requires-python = ">=3.15"
1501
1501
  dependencies = [
@@ -1504,28 +1504,27 @@ dependencies = [
1504
1504
  { name = "mdformat" },
1505
1505
  { name = "mdformat-gfm" },
1506
1506
  { name = "packaging" },
1507
- { name = "pyyaml" },
1508
1507
  { name = "towncrier" },
1509
1508
  ]
1510
1509
  index = "https://pypi.org/simple/"
1511
1510
 
1512
1511
  [packages.sdist]
1513
- name = "release_creator-4.1.0.tar.gz"
1514
- upload-time = 2026-10-26 18:24:45.805437+00:00
1515
- url = "https://files.pythonhosted.org/packages/7f/fd/05d7f3c604476a238d67d5aaa2a4085312e7078c193dbd7ad99ad48d560d/release_creator-4.1.0.tar.gz"
1516
- size = 186016
1512
+ name = "release_creator-4.4.0.tar.gz"
1513
+ upload-time = 2026-11-02 21:44:48.475063+00:00
1514
+ url = "https://files.pythonhosted.org/packages/d8/cf/8f376cc925c26fa5434d327ba03f4ed709b80d2077edda865fc3b2fe1940/release_creator-4.4.0.tar.gz"
1515
+ size = 171450
1517
1516
 
1518
1517
  [packages.sdist.hashes]
1519
- sha256 = "c783037f5ca2efc16fa7cccfb1c2abf0a442f116a63ca82bd7bfb7e2a8343a15"
1518
+ sha256 = "263d518ddee6371fa13d25bd07f7b5af0fa7a6e421b16f1e8143b0a9443bc84d"
1520
1519
 
1521
1520
  [[packages.wheels]]
1522
- name = "release_creator-4.1.0-py3-none-any.whl"
1523
- upload-time = 2026-10-26 18:24:44.353933+00:00
1524
- url = "https://files.pythonhosted.org/packages/30/d0/38480e99025c021d07e0710af02547562dfadbd798bef26dc01869a3f81e/release_creator-4.1.0-py3-none-any.whl"
1525
- size = 52922
1521
+ name = "release_creator-4.4.0-py3-none-any.whl"
1522
+ upload-time = 2026-11-02 21:44:47.195366+00:00
1523
+ url = "https://files.pythonhosted.org/packages/7b/29/6f2a3158b082b3bf8a94eb93662d80b4db4212abea0fc1fae07ac9a043da/release_creator-4.4.0-py3-none-any.whl"
1524
+ size = 54784
1526
1525
 
1527
1526
  [packages.wheels.hashes]
1528
- sha256 = "67deae16d11ac261a1512f18a22c0cf13418f43afc3e56cb74e58ad4422062e3"
1527
+ sha256 = "560ed208cca0dc53bc227878e5596e3e26e44fa277658c5d0dc662901d95f8cb"
1529
1528
 
1530
1529
  [[packages]]
1531
1530
  name = "requests"
@@ -2529,7 +2528,6 @@ command-line = [
2529
2528
  "--all-groups",
2530
2529
  "--all-extras",
2531
2530
  "--no-cache",
2532
- "--upgrade",
2533
2531
  ]
2534
2532
  input-path = "pyproject.toml"
2535
2533
  mode = "universal"
@@ -87,15 +87,15 @@ pkg-meta = [
87
87
  "uv>=0.12.22",
88
88
  ]
89
89
  release-news = [
90
- "release-creator>=4.1",
90
+ "release-creator>=4.4",
91
91
  "towncrier>=26.9",
92
92
  ]
93
93
  release-notes = [
94
- "release-creator>=4.1",
94
+ "release-creator>=4.4",
95
95
  ]
96
96
  release-prepare = [
97
97
  "prek>=0.2",
98
- "release-creator>=4.1",
98
+ "release-creator>=4.4",
99
99
  "towncrier>=26.9",
100
100
  ]
101
101
 
@@ -271,5 +271,5 @@ uploaded-prior-to = "P7D"
271
271
  decision-order = "stable"
272
272
  matrix.python = ">=3.15,<3.16"
273
273
  matrix.platforms = [ "linux_x86_64" ]
274
- # temporary, delete after 2026-11-02
275
- packages.release-creator.uploaded-prior-to = 2026-10-26T18:24:46Z
274
+ # release-creator 4.4.0 needs a seven-day cutoff exception through 2026-11-09.
275
+ packages.release-creator.uploaded-prior-to = 2026-11-02T21:45:00Z
@@ -4,13 +4,17 @@ from __future__ import annotations
4
4
 
5
5
  import json
6
6
  import logging
7
+ import os
8
+ import stat
7
9
  from contextlib import contextmanager, suppress
8
10
  from hashlib import sha256
11
+ from os import fsencode
12
+ from pathlib import Path
13
+ from tempfile import NamedTemporaryFile
9
14
  from typing import TYPE_CHECKING, Final, Protocol, runtime_checkable
10
15
 
11
16
  if TYPE_CHECKING:
12
17
  from collections.abc import Generator
13
- from pathlib import Path
14
18
 
15
19
  _LOGGER: Final[logging.Logger] = logging.getLogger(__name__)
16
20
 
@@ -79,23 +83,58 @@ class DiskContentStore:
79
83
  def read(self) -> dict | None:
80
84
  data, bad_format = None, False
81
85
  try:
82
- data = json.loads(self._file.read_text(encoding="utf-8"))
83
- except ValueError:
86
+ data, bad_format = self._read_entry()
87
+ except (ValueError, RecursionError):
84
88
  bad_format = True
85
89
  except OSError:
86
90
  _LOGGER.debug("failed to read %s", self._file, exc_info=True)
91
+ bad_format = self._file.is_symlink()
87
92
  else:
88
- _LOGGER.debug("got python info from %s", self._file)
89
- return data
93
+ if not bad_format:
94
+ _LOGGER.debug("got python info from %s", self._file)
95
+ return data
90
96
  if bad_format:
91
97
  with suppress(OSError):
92
98
  self.remove()
93
99
  return None
94
100
 
101
+ def _read_entry(self) -> tuple[dict | None, bool]:
102
+ with open(self._file, encoding="utf-8", opener=self._open_entry) as file:
103
+ status = os.fstat(file.fileno())
104
+ if not stat.S_ISREG(status.st_mode) or (
105
+ hasattr(os, "geteuid") and (status.st_uid not in {os.geteuid(), 0} or status.st_mode & 0o022)
106
+ ):
107
+ _LOGGER.warning("ignoring untrusted cache entry at %s", self._file)
108
+ return None, True
109
+ # A 1 MiB query can expand to 12 MiB when supplementary Unicode is escaped.
110
+ if status.st_size > 16 << 20:
111
+ _LOGGER.warning("ignoring oversized cache entry at %s", self._file)
112
+ return None, True
113
+ return json.load(file), False
114
+
115
+ @staticmethod
116
+ def _open_entry(path: str, flags: int) -> int:
117
+ return os.open(path, flags | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
118
+
95
119
  def write(self, content: dict) -> None:
96
120
  self._folder.mkdir(parents=True, exist_ok=True)
97
- self._file.write_text(json.dumps(content, sort_keys=True, indent=2), encoding="utf-8")
98
- _LOGGER.debug("wrote python info at %s", self._file)
121
+ temporary: Path | None = None
122
+ try:
123
+ with NamedTemporaryFile(
124
+ mode="w", encoding="utf-8", dir=self._folder, prefix=f".{self._key}.", delete=False
125
+ ) as file:
126
+ temporary = Path(file.name)
127
+ # Compact encoding avoids indentation growth and the streaming encoder's recursion limit.
128
+ file.write(json.dumps(content, sort_keys=True))
129
+ temporary.replace(self._file)
130
+ except OSError:
131
+ _LOGGER.debug("failed to write %s", self._file, exc_info=True)
132
+ else:
133
+ _LOGGER.debug("wrote python info at %s", self._file)
134
+ finally:
135
+ if temporary is not None:
136
+ with suppress(OSError):
137
+ temporary.unlink(missing_ok=True)
99
138
 
100
139
  def remove(self) -> None:
101
140
  with suppress(OSError):
@@ -106,9 +145,15 @@ class DiskContentStore:
106
145
  def locked(self) -> Generator[None]:
107
146
  from filelock import FileLock # ruff:ignore[import-outside-top-level]
108
147
 
109
- lock_path = self._folder / f"{self._key}.lock"
110
- lock_path.parent.mkdir(parents=True, exist_ok=True)
111
- with FileLock(str(lock_path)):
148
+ self._folder.mkdir(parents=True, exist_ok=True)
149
+ if os.name == "posix":
150
+ group_shared = bool(self._folder.stat().st_mode & stat.S_IWGRP)
151
+ lock_folder = self._folder / "locks-v2"
152
+ lock_folder.mkdir(mode=0o770 if group_shared else 0o700, exist_ok=True)
153
+ lock = FileLock(str(lock_folder / f"{self._key}.lock"), mode=0o660 if group_shared else 0o600)
154
+ else:
155
+ lock = FileLock(str(self._folder / f"{self._key}.lock"))
156
+ with lock:
112
157
  yield
113
158
 
114
159
 
@@ -120,25 +165,52 @@ class DiskCache:
120
165
  """
121
166
 
122
167
  def __init__(self, root: Path) -> None:
123
- self._root = root
168
+ self._root = Path(os.path.abspath(root)) # ruff:ignore[os-path-abspath] # resolve() follows untrusted links
124
169
 
125
170
  @property
126
171
  def _py_info_dir(self) -> Path:
127
172
  return self._root / "py_info" / "4"
128
173
 
129
- def py_info(self, path: Path) -> DiskContentStore:
174
+ def py_info(self, path: Path) -> ContentStore:
130
175
  """
131
176
  Return the content store for the interpreter at *path*.
132
177
 
133
178
  :param path: absolute path to a Python executable.
134
179
  """
135
- key = sha256(str(path).encode("utf-8")).hexdigest()
180
+ if not self._trusted_folder():
181
+ return NoOpContentStore()
182
+ key = sha256(fsencode(path)).hexdigest()
136
183
  return DiskContentStore(self._py_info_dir, key)
137
184
 
185
+ def _trusted_folder(self) -> bool:
186
+ if not hasattr(os, "geteuid"):
187
+ return True
188
+ user_id = os.geteuid()
189
+ folder = self._py_info_dir
190
+ private = {self._root, folder.parent, folder}
191
+ for candidate in (*reversed(folder.parents), folder):
192
+ try:
193
+ try:
194
+ status = candidate.lstat()
195
+ except FileNotFoundError:
196
+ candidate.mkdir(exist_ok=True)
197
+ status = candidate.lstat()
198
+ except OSError:
199
+ _LOGGER.warning("not caching in %s", candidate, exc_info=True)
200
+ return False
201
+ if (
202
+ not stat.S_ISDIR(status.st_mode)
203
+ or status.st_uid not in {user_id, 0}
204
+ or (status.st_mode & 0o022 and (candidate in private or not status.st_mode & stat.S_ISVTX))
205
+ ):
206
+ _LOGGER.warning("not caching in untrusted directory %s", candidate)
207
+ return False
208
+ return True
209
+
138
210
  def py_info_clear(self) -> None:
139
211
  """Remove all cached interpreter information."""
140
212
  folder = self._py_info_dir
141
- if folder.exists():
213
+ if folder.exists() and self._trusted_folder():
142
214
  for entry in folder.iterdir():
143
215
  if entry.suffix == ".json":
144
216
  with suppress(OSError):