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.
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/news.yaml +2 -5
- python_discovery-1.9.2/.github/workflows/scorecard.yaml +26 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/PKG-INFO +3 -1
- {python_discovery-1.9.1 → python_discovery-1.9.2}/README.md +2 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/changelog.rst +77 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/explanation.rst +57 -15
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/how-to/standalone-usage.rst +3 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/pylock.toml +12 -14
- {python_discovery-1.9.1 → python_discovery-1.9.2}/pyproject.toml +5 -5
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_cache.py +86 -14
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_cached_py_info.py +175 -49
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_discovery.py +55 -27
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_py_info.py +22 -11
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_py_info_collect.py +12 -4
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_specifier.py +8 -0
- python_discovery-1.9.2/src/python_discovery/_windows/_cancel_io.py +51 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_windows/_pep514.py +10 -5
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/py_info/test_py_info.py +9 -3
- python_discovery-1.9.2/tests/test_cache.py +381 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_cached_py_info.py +223 -22
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_discovery.py +404 -15
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_py_info_collect.py +65 -4
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_py_info_extra.py +92 -3
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_query_timeout.py +27 -5
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_specifier.py +5 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/windows/test_windows.py +13 -1
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/windows/test_windows_pep514.py +35 -1
- python_discovery-1.9.1/tests/test_cache.py +0 -115
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/FUNDING.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/SECURITY.md +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/THREAT_MODEL.md +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/dependabot.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/release.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/check.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/codeql.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/prepare-release.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/release.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.github/workflows/upgrade-release-tools.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.gitignore +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.pre-commit-config.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.readthedocs.yaml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/.readthedocs.yml +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/CODE_OF_CONDUCT.md +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/LICENSE +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/_static/custom.css +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/_static/github.svg +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/_static/logo.svg +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/changelog/template.jinja2 +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/conf.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/contributing.rst +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/index.rst +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/reference/api.rst +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/reference/environment-variables.rst +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/docs/tutorial/getting-started.rst +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/__init__.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_compat.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_py_spec.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_windows/__init__.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/_windows/_propose.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/src/python_discovery/py.typed +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tasks/old_target_check.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tasks/old_target_check.sh +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/conftest.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/py_info/test_py_info_exe_based_of.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_cache_recovery.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_discovery_extra.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_iter_interpreters.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_py_spec.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/test_py_spec_extra.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/windows/conftest.py +0 -0
- {python_discovery-1.9.1 → python_discovery-1.9.2}/tests/windows/winreg_mock_values.py +0 -0
- {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@
|
|
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@
|
|
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.
|
|
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
|
[](https://pepy.tech/project/python-discovery)
|
|
40
40
|
[](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml)
|
|
41
41
|
[](https://python-discovery.readthedocs.io/en/latest/?badge=latest)
|
|
42
|
+
[](https://scorecard.dev/viewer/?uri=github.com/tox-dev/python-discovery)
|
|
43
|
+
[](https://www.bestpractices.dev/projects/16262)
|
|
42
44
|
|
|
43
45
|
## What is python-discovery?
|
|
44
46
|
|
|
@@ -5,6 +5,8 @@
|
|
|
5
5
|
[](https://pepy.tech/project/python-discovery)
|
|
6
6
|
[](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml)
|
|
7
7
|
[](https://python-discovery.readthedocs.io/en/latest/?badge=latest)
|
|
8
|
+
[](https://scorecard.dev/viewer/?uri=github.com/tox-dev/python-discovery)
|
|
9
|
+
[](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{"
|
|
16
|
+
TryFirst --> RelPath{"Does spec name a<br>relative directory?"}
|
|
17
17
|
RelPath -->|Yes| TryRel["Resolve relative to cwd"]
|
|
18
|
-
RelPath -->|No|
|
|
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|
|
|
56
|
+
EnvVar -->|Yes| Valid{"Valid directory name?"}
|
|
55
57
|
EnvVar -->|No| File{".python-version<br>names a version?"}
|
|
56
|
-
File -->|Yes|
|
|
58
|
+
File -->|Yes| Valid
|
|
57
59
|
File -->|No| Global{"pyenv global<br>version exists?"}
|
|
58
|
-
Global -->|Yes|
|
|
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.
|
|
95
|
-
|
|
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
|
|
240
|
-
|
|
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 -->
|
|
249
|
-
|
|
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
|
|
289
|
-
found, and the floor
|
|
290
|
-
|
|
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
|
|
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.
|
|
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.
|
|
1514
|
-
upload-time = 2026-
|
|
1515
|
-
url = "https://files.pythonhosted.org/packages/
|
|
1516
|
-
size =
|
|
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 = "
|
|
1518
|
+
sha256 = "263d518ddee6371fa13d25bd07f7b5af0fa7a6e421b16f1e8143b0a9443bc84d"
|
|
1520
1519
|
|
|
1521
1520
|
[[packages.wheels]]
|
|
1522
|
-
name = "release_creator-4.
|
|
1523
|
-
upload-time = 2026-
|
|
1524
|
-
url = "https://files.pythonhosted.org/packages/
|
|
1525
|
-
size =
|
|
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 = "
|
|
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.
|
|
90
|
+
"release-creator>=4.4",
|
|
91
91
|
"towncrier>=26.9",
|
|
92
92
|
]
|
|
93
93
|
release-notes = [
|
|
94
|
-
"release-creator>=4.
|
|
94
|
+
"release-creator>=4.4",
|
|
95
95
|
]
|
|
96
96
|
release-prepare = [
|
|
97
97
|
"prek>=0.2",
|
|
98
|
-
"release-creator>=4.
|
|
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
|
-
#
|
|
275
|
-
packages.release-creator.uploaded-prior-to = 2026-
|
|
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 =
|
|
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
|
-
|
|
89
|
-
|
|
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
|
-
|
|
98
|
-
|
|
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
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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) ->
|
|
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
|
-
|
|
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):
|