python-discovery 1.6.4__tar.gz → 1.9.1__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 (76) hide show
  1. python_discovery-1.9.1/.github/SECURITY.md +56 -0
  2. python_discovery-1.9.1/.github/THREAT_MODEL.md +106 -0
  3. python_discovery-1.9.1/.github/dependabot.yaml +30 -0
  4. {python_discovery-1.6.4 → python_discovery-1.9.1}/.github/release.yaml +1 -0
  5. {python_discovery-1.6.4 → python_discovery-1.9.1}/.github/workflows/check.yaml +30 -43
  6. python_discovery-1.9.1/.github/workflows/codeql.yaml +41 -0
  7. python_discovery-1.9.1/.github/workflows/news.yaml +33 -0
  8. python_discovery-1.9.1/.github/workflows/prepare-release.yaml +23 -0
  9. python_discovery-1.9.1/.github/workflows/release.yaml +117 -0
  10. python_discovery-1.9.1/.github/workflows/upgrade-release-tools.yaml +22 -0
  11. {python_discovery-1.6.4 → python_discovery-1.9.1}/.gitignore +1 -0
  12. python_discovery-1.9.1/.pre-commit-config.yaml +68 -0
  13. {python_discovery-1.6.4 → python_discovery-1.9.1}/PKG-INFO +4 -21
  14. python_discovery-1.9.1/docs/_static/github.svg +1 -0
  15. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/changelog/template.jinja2 +10 -13
  16. python_discovery-1.9.1/docs/changelog.rst +546 -0
  17. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/conf.py +17 -2
  18. python_discovery-1.9.1/docs/contributing.rst +22 -0
  19. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/explanation.rst +18 -5
  20. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/how-to/standalone-usage.rst +6 -0
  21. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/index.rst +1 -0
  22. python_discovery-1.9.1/pylock.toml +2539 -0
  23. {python_discovery-1.6.4 → python_discovery-1.9.1}/pyproject.toml +60 -16
  24. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/__init__.py +2 -1
  25. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_discovery.py +22 -10
  26. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_py_info.py +27 -5
  27. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_py_info_collect.py +24 -0
  28. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_py_spec.py +60 -39
  29. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_specifier.py +4 -6
  30. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/py_info/test_py_info.py +49 -2
  31. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_discovery.py +125 -0
  32. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_iter_interpreters.py +86 -0
  33. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_py_info_extra.py +74 -5
  34. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_py_spec.py +56 -1
  35. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_py_spec_extra.py +46 -5
  36. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_specifier.py +8 -0
  37. {python_discovery-1.6.4 → python_discovery-1.9.1}/tox.toml +1 -8
  38. python_discovery-1.6.4/.github/SECURITY.md +0 -9
  39. python_discovery-1.6.4/.github/dependabot.yaml +0 -17
  40. python_discovery-1.6.4/.github/workflows/prepare-release.yaml +0 -156
  41. python_discovery-1.6.4/.github/workflows/release.yaml +0 -105
  42. python_discovery-1.6.4/.pre-commit-config.yaml +0 -49
  43. python_discovery-1.6.4/docs/changelog.rst +0 -291
  44. python_discovery-1.6.4/tasks/release.py +0 -82
  45. {python_discovery-1.6.4 → python_discovery-1.9.1}/.github/FUNDING.yaml +0 -0
  46. {python_discovery-1.6.4 → python_discovery-1.9.1}/.readthedocs.yaml +0 -0
  47. {python_discovery-1.6.4 → python_discovery-1.9.1}/.readthedocs.yml +0 -0
  48. {python_discovery-1.6.4 → python_discovery-1.9.1}/CODE_OF_CONDUCT.md +0 -0
  49. {python_discovery-1.6.4 → python_discovery-1.9.1}/LICENSE +0 -0
  50. {python_discovery-1.6.4 → python_discovery-1.9.1}/README.md +0 -0
  51. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/_static/custom.css +0 -0
  52. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/_static/logo.svg +0 -0
  53. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/reference/api.rst +0 -0
  54. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/reference/environment-variables.rst +0 -0
  55. {python_discovery-1.6.4 → python_discovery-1.9.1}/docs/tutorial/getting-started.rst +0 -0
  56. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_cache.py +0 -0
  57. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_cached_py_info.py +0 -0
  58. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_compat.py +0 -0
  59. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_windows/__init__.py +0 -0
  60. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_windows/_pep514.py +0 -0
  61. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/_windows/_propose.py +0 -0
  62. {python_discovery-1.6.4 → python_discovery-1.9.1}/src/python_discovery/py.typed +0 -0
  63. {python_discovery-1.6.4 → python_discovery-1.9.1}/tasks/old_target_check.py +0 -0
  64. {python_discovery-1.6.4 → python_discovery-1.9.1}/tasks/old_target_check.sh +0 -0
  65. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/conftest.py +0 -0
  66. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/py_info/test_py_info_exe_based_of.py +0 -0
  67. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_cache.py +0 -0
  68. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_cache_recovery.py +0 -0
  69. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_cached_py_info.py +0 -0
  70. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_discovery_extra.py +0 -0
  71. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_py_info_collect.py +0 -0
  72. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/test_query_timeout.py +0 -0
  73. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/windows/conftest.py +0 -0
  74. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/windows/test_windows.py +0 -0
  75. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/windows/test_windows_pep514.py +0 -0
  76. {python_discovery-1.6.4 → python_discovery-1.9.1}/tests/windows/winreg_mock_values.py +0 -0
@@ -0,0 +1,56 @@
1
+ # Security policy
2
+
3
+ python-discovery is a Python library that finds Python interpreters on a machine and reports their metadata. This policy
4
+ says how to report a security problem and how we decide whether a report is one.
5
+
6
+ ## Reporting a vulnerability
7
+
8
+ **Do not open a public issue for a security problem.** Use
9
+ [GitHub's private vulnerability reporting](https://github.com/tox-dev/python-discovery/security/advisories/new). If
10
+ neither works for you, email [gaborjbernat@gmail.com](mailto:gaborjbernat@gmail.com).
11
+
12
+ Include what the attacker controls and what they gain, the steps or a proof of concept, and the versions and platform
13
+ you tested. Write the report yourself; unreviewed tool or model output takes longer to triage.
14
+
15
+ ## What to expect
16
+
17
+ Volunteers maintain python-discovery, with no on-call rotation. We aim to acknowledge a report within **5 working days**
18
+ and assess it within **15 working days**. Fixes are developed in a private fork attached to the draft advisory, ship in
19
+ a new release, and the advisory, with a CVE requested through GitHub, goes out with that release. The default embargo is
20
+ **90 days** from the report; we agree any change with the reporter. We credit reporters in the advisory under the name
21
+ they choose, or not at all. There is no bug bounty.
22
+
23
+ ## Supported versions
24
+
25
+ Only the latest release receives fixes. Confirm the problem reproduces on it before reporting.
26
+
27
+ ## Vulnerability or bug
28
+
29
+ A report is a vulnerability when an attacker who controls only an input that the [threat model](THREAT_MODEL.md) lists
30
+ as untrusted breaks a guarantee python-discovery makes. A report that first needs control of something the threat model
31
+ trusts, such as an executable on `PATH` or in a version manager's directory, is a bug: we fix it in the open and publish
32
+ no advisory. Classify by who supplies the dangerous input, not by how bad the outcome sounds.
33
+
34
+ **In scope**
35
+
36
+ - Executing a binary from a location the documented search order does not include, such as the current directory through
37
+ an empty `PATH` entry.
38
+ - A cache entry from one interpreter being reported for another, or surviving a change of the binary.
39
+ - Interrogation output from one candidate being parsed as another candidate's metadata.
40
+ - A spec's version, implementation, architecture, free-threading or debug constraint passing for a shim or launcher
41
+ while the interpreter it resolves to fails it.
42
+ - A PEP 514 record or a spec making discovery run a program other than the candidate with its registered arguments.
43
+ - Another local user writing a shared cache directory so a victim accepts an interpreter, or metadata, that discovery
44
+ would otherwise reject.
45
+ - A small candidate response exhausting memory or processes.
46
+
47
+ **Out of scope**
48
+
49
+ - A malicious interpreter in a searched location: python-discovery runs candidates to learn about them, so whoever can
50
+ place one there already runs code as the user.
51
+ - Values in the process environment (`PATH`, `PYENV_ROOT`, `UV_PYTHON_INSTALL_DIR`, `PY_DISCOVERY_TIMEOUT`) and the
52
+ Windows registry entries of PEP 514.
53
+ - A `.python-version` file choosing among interpreters that discovery would find anyway.
54
+ - Tampering with a cache directory only the caller can write.
55
+
56
+ If you cannot tell which side a finding falls on, report it privately and we will decide.
@@ -0,0 +1,106 @@
1
+ # Threat model
2
+
3
+ This model says what python-discovery trusts, where untrusted input enters, and which guarantees hold at each boundary,
4
+ so a report can be classified as a vulnerability or a bug. [SECURITY.md](SECURITY.md) covers reporting; if the two
5
+ disagree, SECURITY.md wins and we fix this file.
6
+
7
+ ## How python-discovery works
8
+
9
+ A caller passes a requirement such as `python3.12` or `>=3.11,<3.13`. python-discovery walks `try_first_with` paths, the
10
+ running interpreter, the PEP 514 registry on Windows, `PATH` (resolving pyenv, mise and asdf shims to the binary they
11
+ select), and uv's install directories. It runs each candidate with a bundled interrogation script and reads a JSON
12
+ answer framed by two random cookies, then caches that answer in a directory the caller supplies, valid while the
13
+ binary's path and modification time, the script's hash and any PEP 514 arguments stay the same.
14
+
15
+ ```mermaid
16
+ flowchart LR
17
+ caller["Caller<br/>spec, env, cache dir (trusted)"] --> pd["python-discovery"]
18
+ pd -->|search| locs[("PATH, version managers,<br/>PEP 514 registry (trusted)")]
19
+ pd -->|"run candidate + script"| py["Candidate interpreter"]
20
+ py -->|"JSON between cookies"| pd
21
+ pd <-->|"checked against path, mtime,<br/>script hash, PEP 514 args"| cache[("Cache dir")]
22
+ classDef trusted fill:#cfe4ff,stroke:#1f6feb,color:#0b1f3a;
23
+ classDef boundary fill:#ffe3a3,stroke:#d29200,color:#3a2c00;
24
+ class caller,pd,locs trusted;
25
+ class py,cache boundary;
26
+ ```
27
+
28
+ ## Compared with similar tools
29
+
30
+ We drew the boundary where comparable projects in other ecosystems draw theirs. The shared rule, stated by the
31
+ [Node.js threat model](https://github.com/nodejs/node/blob/main/SECURITY.md#the-nodejs-threat-model), is that a report
32
+ which first needs a trusted element compromised is out of scope; the first triage question, as
33
+ [DOMPurify](https://github.com/cure53/DOMPurify/blob/main/SECURITY.md#what-we-consider-a-vulnerability) puts it, is what
34
+ the attacker controls.
35
+
36
+ | Project | Language | Where it draws the line |
37
+ | ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
38
+ | [Go `os/exec` path lookup](https://go.dev/blog/path-security) | Go | Refuses to run a binary found through the current directory; python-discovery skips empty `PATH` entries for the same reason. |
39
+ | [nvm](https://github.com/nvm-sh/nvm/blob/HEAD/.github/THREAT_MODEL.md) | Shell | Trusts what it installs and executes as the user; treats mirror metadata, not payloads, as the untrusted boundary. |
40
+ | [uv](https://github.com/astral-sh/uv/security/policy) | Rust | Its policy says invoking the Python interpreters it finds, to read their metadata, is not a vulnerability. |
41
+
42
+ ## Trusted
43
+
44
+ An attacker who controls any of these already has what python-discovery could give them:
45
+
46
+ - The caller and the spec, environment mapping, cache directory and `try_first_with` paths it passes.
47
+ - Every directory searched: `PATH` entries, version-manager roots and install directories, and the PEP 514 registry,
48
+ including `ExecutableArguments`.
49
+ - The interpreters found there; running them is how discovery works.
50
+ - A cache directory that only the caller can write (for example virtualenv's app-data).
51
+
52
+ ## Untrusted inputs
53
+
54
+ | Input | Comes from | What python-discovery guarantees |
55
+ | ----------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
56
+ | The current working directory | Wherever the caller happens to run | Empty `PATH` components, which shells read as the current directory, are skipped. |
57
+ | Interrogation stdout | Startup noise or a `sitecustomize` that prints | Only the JSON between two per-run random cookies is parsed; anything else is a failed candidate. |
58
+ | Cache entries | Earlier runs, possibly of another interpreter build | Reused only when the binary's path and modification time, the script hash and the PEP 514 arguments all match. |
59
+ | A shared cache directory | Another local user who can write it | Must not make a victim accept an interpreter or metadata that discovery would reject; report any way it does. |
60
+
61
+ ## Threats and controls
62
+
63
+ | STRIDE | Threat | Control |
64
+ | ---------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
65
+ | Spoofing | Output printed by a candidate's startup code impersonates its metadata. | Random start and end cookies frame the answer. |
66
+ | Tampering | A stale cache entry describes a binary that has since been replaced. | The entry records the binary's modification time, the script's hash and the PEP 514 arguments. |
67
+ | Denial of service | A candidate hangs during interrogation. | The interrogation has a timeout, configurable with `PY_DISCOVERY_TIMEOUT`. |
68
+ | Elevation of privilege | A binary in the current directory is picked up through `PATH`. | Empty `PATH` entries are skipped. |
69
+
70
+ ## Release chain
71
+
72
+ Releases run on the shared [tox-dev/github-workflows](https://github.com/tox-dev/github-workflows) pipeline. A release
73
+ App, not a person, pushes the release commit and tag; the build installs its tools from a hash-checked `pylock.toml`
74
+ resolved with a seven-day upload cooldown by default; PyPI receives the files through
75
+ [trusted publishing](https://docs.pypi.org/trusted-publishers/) with attestations, and the GitHub Release is immutable.
76
+ Every workflow pins third-party actions to a commit SHA.
77
+
78
+ ## Vulnerability or bug
79
+
80
+ | Report | Verdict | Why |
81
+ | --------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
82
+ | A `python3` in the working directory runs because `PATH` ends with `:` | Vulnerability | The empty entry must not reach the current directory. |
83
+ | A `pyenv` shim that is malware runs during discovery | Not a vulnerability | Searched locations are trusted. |
84
+ | A cached answer for `/usr/bin/python3` is returned after the OS upgraded it | Bug | Cache correctness, crossing no boundary; a vulnerability only if it can point at a different binary. |
85
+ | `PY_DISCOVERY_TIMEOUT=inf` lets a hung interpreter block forever | Not a vulnerability | The environment is trusted and the value is documented. |
86
+
87
+ ## Severity
88
+
89
+ - **High:** argument handling runs a separate command the attacker chose, or another local user poisons a shared cache
90
+ so a victim runs an interpreter outside the requested constraints, without control of the victim's `PATH`, registry or
91
+ interpreters.
92
+ - **Medium:** cache poisoning changes security-relevant metadata without execution, or a small candidate response causes
93
+ sustained memory or process exhaustion.
94
+ - **Low:** the wrong interpreter selected without crossing a privilege boundary, a crash on malformed output, or stale
95
+ metadata from a cache only the caller writes.
96
+
97
+ ## Accepted risks
98
+
99
+ - Discovery executes every candidate it considers; it cannot learn an interpreter's version without running it.
100
+ - PEP 514 `ExecutableArguments` are raw command-line text from the registry, passed to the candidate as written, without
101
+ a shell.
102
+
103
+ ## Keeping this current
104
+
105
+ Revisit this model when python-discovery gains a new input source, network access, a new way to run code, or a new place
106
+ it writes to, and whenever an advisory is published.
@@ -0,0 +1,30 @@
1
+ version: 2
2
+ multi-ecosystem-groups:
3
+ dependencies:
4
+ schedule:
5
+ interval: weekly
6
+ day: tuesday
7
+ labels:
8
+ - dependencies
9
+ - skip news
10
+ updates:
11
+ - package-ecosystem: github-actions
12
+ directory: /
13
+ patterns:
14
+ - '*'
15
+ multi-ecosystem-group: dependencies
16
+ labels:
17
+ - dependencies
18
+ - skip news
19
+ cooldown:
20
+ default-days: 7
21
+ - package-ecosystem: pre-commit
22
+ directory: /
23
+ patterns:
24
+ - '*'
25
+ multi-ecosystem-group: dependencies
26
+ labels:
27
+ - dependencies
28
+ - skip news
29
+ cooldown:
30
+ default-days: 7
@@ -2,4 +2,5 @@ changelog:
2
2
  exclude:
3
3
  authors:
4
4
  - dependabot[bot]
5
+ - github-actions[bot]
5
6
  - pre-commit-ci[bot]
@@ -1,11 +1,11 @@
1
- name: check
1
+ name: 🧪 check
2
2
  on:
3
3
  workflow_dispatch:
4
4
  push:
5
5
  branches: ["main"]
6
6
  tags-ignore: ["**"]
7
7
  pull_request:
8
- types: [opened, synchronize, reopened, labeled, unlabeled]
8
+ types: [opened, synchronize, reopened]
9
9
  schedule:
10
10
  - cron: "0 8 * * *"
11
11
  concurrency:
@@ -15,6 +15,7 @@ permissions:
15
15
  contents: read
16
16
  jobs:
17
17
  test:
18
+ name: 🧪 Test
18
19
  runs-on: ubuntu-26.04
19
20
  strategy:
20
21
  fail-fast: false
@@ -33,80 +34,66 @@ jobs:
33
34
  - dev
34
35
  - pkg_meta
35
36
  steps:
36
- - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
37
+ - name: 📥 Check out code
38
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
37
39
  with:
38
40
  fetch-depth: 0
39
41
  persist-credentials: false
40
- - name: Install the latest version of uv
41
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
42
+ - name: 🐍 Install uv
43
+ uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
42
44
  with:
45
+ version: latest-known
43
46
  python-version: "3.15"
44
47
  enable-cache: false
45
48
  cache-dependency-glob: "pyproject.toml"
46
49
  github-token: ${{ secrets.GITHUB_TOKEN }}
47
- - name: Install tox
50
+ - name: 📦 Install tox
48
51
  run: uv tool install --python-preference only-managed --python 3.15 tox --with tox-uv
49
- - name: Install Python
52
+ - name: 🐍 Install Python
50
53
  if: startsWith(matrix.env, '3.') && matrix.env != '3.15'
51
54
  run: uv python install --python-preference only-managed ${{ matrix.env }}
52
- - name: Setup test suite
55
+ - name: 📦 Set up test suite
53
56
  run: tox run -vv --notest --skip-missing-interpreters false -e ${{ matrix.env }}
54
- - name: Run test suite
57
+ - name: 🧪 Run test suite
55
58
  run: tox run --skip-pkg-install -e ${{ matrix.env }}
56
59
  env:
57
60
  PYTEST_ADDOPTS: "-vv --durations=20"
58
61
  DIFF_AGAINST: HEAD
59
62
  old-target:
63
+ name: 🧪 Test on old target
60
64
  runs-on: ubuntu-26.04
61
65
  steps:
62
- - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
66
+ - name: 📥 Check out code
67
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
63
68
  with:
64
69
  fetch-depth: 0
65
70
  persist-credentials: false
66
- - name: Install the latest version of uv
67
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
71
+ - name: 🐍 Install uv
72
+ uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
68
73
  with:
74
+ version: latest-known
69
75
  python-version: "3.15"
70
76
  enable-cache: false
71
77
  cache-dependency-glob: "pyproject.toml"
72
78
  github-token: ${{ secrets.GITHUB_TOKEN }}
73
- - name: Build the wheel
79
+ - name: 🏗️ Build the wheel
74
80
  run: uv build --wheel --out-dir dist .
75
81
  - parallel:
76
- - name: Discover Python 3.6
82
+ - name: 🧪 Discover Python 3.6
77
83
  run: tasks/old_target_check.sh 3.6 discover
78
- - name: Discover Python 3.7
84
+ - name: 🧪 Discover Python 3.7
79
85
  run: tasks/old_target_check.sh 3.7 discover
80
- - name: Reject Python 3.5
86
+ - name: 🧪 Reject Python 3.5
81
87
  run: tasks/old_target_check.sh 3.5 rejected
82
- - name: Reject Python 2.7
88
+ - name: 🧪 Reject Python 2.7
83
89
  run: tasks/old_target_check.sh 2.7 rejected
84
- changelog:
85
- if: github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'skip news')
86
- runs-on: ubuntu-24.04
87
- steps:
88
- - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
89
- with:
90
- fetch-depth: 0
91
- persist-credentials: false
92
- - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
93
- with:
94
- python-version: "3.15"
95
- enable-cache: false
96
- - run: uvx towncrier check --compare-with "origin/${GITHUB_BASE_REF}"
97
90
  gate:
98
- name: Required checks pass
99
- if: always()
100
- needs: [test, old-target, changelog]
101
- runs-on: ubuntu-24.04
91
+ name: 🚦 ${{ github.event_name == 'pull_request' && 'Required checks pass' || 'Non-PR checks pass' }}
92
+ if: ${{ !cancelled() }} # codespell:ignore cancelled
93
+ needs: [test, old-target]
94
+ runs-on: ubuntu-26.04
102
95
  steps:
103
- - env:
96
+ - name: 🚦 Require all needed jobs to pass
97
+ env:
104
98
  NEEDS_JSON: ${{ toJSON(needs) }}
105
- run: |
106
- jq -e '
107
- all(
108
- to_entries[];
109
- .value.result == "success" or
110
- (.key == "changelog" and .value.result == "skipped")
111
- )
112
- ' <<< "$NEEDS_JSON"
99
+ run: jq -e 'all(to_entries[]; .value.result == "success")' <<<"$NEEDS_JSON"
@@ -0,0 +1,41 @@
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 ${{ matrix.language }}
16
+ runs-on: ubuntu-26.04
17
+ permissions:
18
+ contents: read
19
+ security-events: write
20
+ strategy:
21
+ fail-fast: false
22
+ matrix:
23
+ language: [actions, python]
24
+ steps:
25
+ - name: 📥 Check out code
26
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
27
+ with:
28
+ persist-credentials: false
29
+ - name: 🛡️ Initialize CodeQL
30
+ uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
31
+ with:
32
+ languages: ${{ matrix.language }}
33
+ build-mode: none
34
+ queries: security-extended
35
+ config: |
36
+ paths-ignore:
37
+ - tests
38
+ - name: 🛡️ Analyze
39
+ uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
40
+ with:
41
+ category: "/language:${{ matrix.language }}"
@@ -0,0 +1,33 @@
1
+ name: 📝 Changelog
2
+ on:
3
+ pull_request:
4
+ types: [opened, reopened, synchronize, labeled, unlabeled]
5
+ concurrency:
6
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
7
+ cancel-in-progress: true
8
+ permissions:
9
+ contents: read
10
+ pull-requests: read
11
+ jobs:
12
+ changelog:
13
+ name: 📝 News fragment
14
+ runs-on: ubuntu-26.04
15
+ steps:
16
+ - name: 📥 Check out code
17
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
18
+ with:
19
+ fetch-depth: 0
20
+ persist-credentials: false
21
+ - name: 🐍 Install uv
22
+ uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
23
+ with:
24
+ version: latest-known
25
+ python-version: "3.15"
26
+ enable-cache: false
27
+ - name: 📦 Install locked release tools
28
+ uses: tox-dev/github-workflows/install-locked-tools@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
29
+ with:
30
+ groups: release-news
31
+ venv: ${{ runner.temp }}/release-tools
32
+ - name: 🔍 Validate news fragments
33
+ uses: tox-dev/github-workflows/validate-news@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
@@ -0,0 +1,23 @@
1
+ name: 🏷️ Prepare release
2
+ on:
3
+ workflow_dispatch:
4
+ inputs:
5
+ bump:
6
+ description: Version bump type
7
+ required: true
8
+ type: choice
9
+ options: [auto, major, minor, patch]
10
+ default: auto
11
+ permissions: {}
12
+ jobs:
13
+ prepare:
14
+ name: 🏷️ Prepare Towncrier release
15
+ uses: tox-dev/github-workflows/.github/workflows/prepare-towncrier-release.yaml@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
16
+ permissions:
17
+ contents: read
18
+ pull-requests: read
19
+ with:
20
+ bump: ${{ inputs.bump }}
21
+ annotated: true
22
+ secrets:
23
+ RELEASE_APP_PRIVATE_KEY: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
@@ -0,0 +1,117 @@
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@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
14
+ permissions:
15
+ contents: read
16
+ notes:
17
+ name: 📝 Render GitHub Release notes
18
+ runs-on: ubuntu-26.04
19
+ permissions:
20
+ contents: read
21
+ outputs:
22
+ artifact-id: ${{ steps.upload.outputs.artifact-id }}
23
+ steps:
24
+ - name: 📥 Check out code
25
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
26
+ with:
27
+ fetch-depth: 0
28
+ persist-credentials: false
29
+ - name: 🐍 Install uv
30
+ uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
31
+ with:
32
+ version: latest-known
33
+ python-version: "3.15"
34
+ enable-cache: false
35
+ - name: 📦 Install locked release tools
36
+ uses: tox-dev/github-workflows/install-locked-tools@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
37
+ with:
38
+ groups: release-notes
39
+ venv: ${{ runner.temp }}/release-tools
40
+ - name: 🏷️ Select previous tag
41
+ id: previous
42
+ uses: tox-dev/github-workflows/select-previous-tag@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
43
+ with:
44
+ tag: ${{ github.ref_name }}
45
+ - name: 📝 Render release notes
46
+ uses: tox-dev/github-workflows/render-release-notes@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
47
+ with:
48
+ tag: ${{ github.ref_name }}
49
+ previous: ${{ steps.previous.outputs.previous }}
50
+ changelog: docs/changelog.rst
51
+ artifact-url: https://pypi.org/project/python-discovery/${{ github.ref_name }}/
52
+ - name: 📤 Upload release notes
53
+ id: upload
54
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
55
+ with:
56
+ name: release-notes
57
+ path: ${{ runner.temp }}/release-notes.md
58
+ if-no-files-found: error
59
+ release:
60
+ name: 🚀 Publish to PyPI
61
+ needs: [build, notes]
62
+ runs-on: ubuntu-26.04
63
+ environment:
64
+ name: release
65
+ url: https://pypi.org/project/python-discovery/${{ github.ref_name }}
66
+ permissions:
67
+ id-token: write
68
+ steps:
69
+ - name: 📩 Download distributions
70
+ uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
71
+ with:
72
+ artifact-ids: ${{ needs.build.outputs.distributions-artifact-id }}
73
+ path: dist/
74
+ - name: 🚀 Publish to PyPI
75
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
76
+ with:
77
+ packages-dir: dist
78
+ github-release:
79
+ name: 🚀 Publish GitHub Release
80
+ needs: [build, notes, release]
81
+ runs-on: ubuntu-26.04
82
+ environment: release
83
+ permissions:
84
+ contents: write
85
+ steps:
86
+ - name: 🐍 Install uv
87
+ uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
88
+ with:
89
+ version: latest-known
90
+ python-version: "3.15"
91
+ enable-cache: false
92
+ ignore-empty-workdir: true
93
+ - name: 📩 Download distributions
94
+ uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
95
+ with:
96
+ artifact-ids: ${{ needs.build.outputs.distributions-artifact-id }}
97
+ path: dist/
98
+ - name: 📩 Download release notes
99
+ uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
100
+ with:
101
+ artifact-ids: ${{ needs.notes.outputs.artifact-id }}
102
+ path: ${{ runner.temp }}
103
+ - name: 🔍 Verify PyPI artifacts
104
+ uses: tox-dev/github-workflows/reconcile-pypi-artifacts@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
105
+ with:
106
+ project: python-discovery
107
+ version: ${{ github.ref_name }}
108
+ dist: dist
109
+ - name: 🚀 Publish GitHub release
110
+ uses: tox-dev/github-workflows/publish-github-release@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
111
+ env:
112
+ GH_TOKEN: ${{ github.token }}
113
+ with:
114
+ tag: ${{ github.ref_name }}
115
+ commit: ${{ github.sha }}
116
+ title: v${{ github.ref_name }}
117
+ notes-file: ${{ runner.temp }}/release-notes.md
@@ -0,0 +1,22 @@
1
+ name: 🔒 Upgrade release tools
2
+ on:
3
+ workflow_dispatch:
4
+ schedule:
5
+ - cron: "0 8 * * 2"
6
+ permissions: {}
7
+ concurrency:
8
+ group: upgrade-release-tools
9
+ cancel-in-progress: false
10
+ jobs:
11
+ upgrade:
12
+ name: 🔀 Upgrade release tools
13
+ uses: tox-dev/github-workflows/.github/workflows/upgrade-release-tools.yaml@57a765127aae73adf7d0e24a7fe0f067f2d3ea3e # 6.2.1
14
+ permissions:
15
+ contents: read
16
+ secrets:
17
+ RELEASE_APP_PRIVATE_KEY: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
18
+ with:
19
+ commit-message: "build(deps): refresh release lock"
20
+ pull-request-title: "build(deps): refresh release tool lock"
21
+ pull-request-body: |-
22
+ Relock `pylock.toml` after the seven-day cutoff.
@@ -3,3 +3,4 @@
3
3
  dist/
4
4
  .tox/
5
5
  /src/python_discovery/_version.py
6
+ /uv.lock
@@ -0,0 +1,68 @@
1
+ ci:
2
+ autoupdate_schedule: quarterly
3
+ default_language_version:
4
+ python: python3.15
5
+ repos:
6
+ - repo: https://github.com/pre-commit/pre-commit-hooks
7
+ rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # frozen: v6.0.0
8
+ hooks:
9
+ - id: end-of-file-fixer
10
+ - id: trailing-whitespace
11
+ - repo: https://github.com/python-jsonschema/check-jsonschema
12
+ rev: 0494aa7fa1314e98913a41227d8f0a515b2c1049 # frozen: 0.38.2
13
+ hooks:
14
+ - id: check-github-workflows
15
+ args: ["--verbose"]
16
+ - repo: https://github.com/codespell-project/codespell
17
+ rev: 57b21406f092110c18776e39b0bda50d37c945c8 # frozen: v2.4.3
18
+ hooks:
19
+ - id: codespell
20
+ - repo: https://github.com/tox-dev/pyproject-fmt
21
+ rev: "50e0f3aee9dc5747a5f173f79a7417403c18dda6" # frozen: v2.30.3
22
+ hooks:
23
+ - id: pyproject-fmt
24
+ - repo: https://github.com/astral-sh/ruff-pre-commit
25
+ rev: "38bfb07c0c64c304f47eb52090f8288150c77730" # frozen: v0.17.1
26
+ hooks:
27
+ - id: ruff-format
28
+ - id: ruff
29
+ args: ["--fix", "--unsafe-fixes", "--exit-non-zero-on-fix"]
30
+ - repo: https://github.com/google/yamlfmt
31
+ rev: "21ca5323a9c87ee37a434e0ca908efc0a89daa07" # frozen: v0.21.0
32
+ hooks:
33
+ - id: yamlfmt
34
+ - repo: https://github.com/executablebooks/mdformat
35
+ rev: 82912cdaea4fb830f751504486a7879c70526547 # frozen: 1.0.0
36
+ hooks:
37
+ - id: mdformat
38
+ args: ["--wrap", "120"]
39
+ additional_dependencies:
40
+ - mdformat-gfm==1.0.0
41
+ - mdformat-ruff==0.1.3
42
+ - repo: https://github.com/scop/pre-commit-shfmt
43
+ rev: 479be5958357ba5ab65ce47172117348516860e9 # frozen: v3.14.1-1
44
+ hooks:
45
+ - id: shfmt
46
+ args: ["-i", "2"]
47
+ - repo: https://github.com/shellcheck-py/shellcheck-py
48
+ rev: 745eface02aef23e168a8afb6b5737818efbea95 # frozen: v0.11.0.1
49
+ hooks:
50
+ - id: shellcheck
51
+ - repo: https://github.com/LilSpazJoekp/docstrfmt
52
+ rev: c1813841673cdcd6cf602dde1edb78a5d5e45235 # frozen: v2.2.1
53
+ hooks:
54
+ - id: docstrfmt
55
+ files: |
56
+ (?x)
57
+ ^docs/changelog[.]rst$ # Only the generated release history.
58
+ args: ["-l", "120", "--preserve-adornments"]
59
+ additional_dependencies:
60
+ - "sphinx==9.1.1"
61
+ - repo: https://github.com/zizmorcore/zizmor-pre-commit
62
+ rev: c92afdf2c6ca336aaa8f39e2bd8d48f62dbd8e1f # frozen: v1.31.1
63
+ hooks:
64
+ - id: zizmor
65
+ - repo: meta
66
+ hooks:
67
+ - id: check-hooks-apply
68
+ - id: check-useless-excludes