Merge stable into main (#2922)

Author: Rowlando13

.github/workflows/lock.yaml

@@ -10,6 +10,7 @@ on:
 permissions:
   issues: write
   pull-requests: write
+  discussions: write
 concurrency:
   group: lock
 jobs:

.github/workflows/pre-commit.yaml

@@ -7,10 +7,19 @@ jobs:
   main:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-    - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-      with:
-        python-version: 3.x
-    - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
-    - uses: pre-commit-ci/lite-action@5d6cc0eb514c891a40562a58a8e71576c5c7fb43 # v1.1.0
-      if: ${{ !cancelled() }}
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0.1
+        with:
+          enable-cache: true
+          prune-cache: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        id: setup-python
+        with:
+          python-version-file: pyproject.toml
+      - uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit|${{ hashFiles('pyproject.toml', '.pre-commit-config.yaml') }}
+      - run: uv run --locked --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files
+      - uses: pre-commit-ci/lite-action@5d6cc0eb514c891a40562a58a8e71576c5c7fb43 # v1.1.0
+        if: ${{ !cancelled() }}

.github/workflows/publish.yaml

@@ -1,25 +1,23 @@
 name: Publish
 on:
   push:
-    tags:
-      - '*'
+    tags: ['*']
 jobs:
   build:
     runs-on: ubuntu-latest
     outputs:
       hash: ${{ steps.hash.outputs.hash }}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0.1
+        with:
+          enable-cache: true
+          prune-cache: false
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
-          python-version: '3.x'
-          cache: pip
-          cache-dependency-path: requirements*/*.txt
-      - run: pip install -r requirements/build.txt
-      # Use the commit date instead of the current date during the build.
+          python-version-file: pyproject.toml
       - run: echo "SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)" >> $GITHUB_ENV
-      - run: python -m build
-      # Generate hashes used for provenance.
+      - run: uv build
       - name: generate hash
         id: hash
         run: cd dist && echo "hash=$(sha256sum * | base64 -w0)" >> $GITHUB_OUTPUT
@@ -37,8 +35,6 @@ jobs:
     with:
       base64-subjects: ${{ needs.build.outputs.hash }}
   create-release:
-    # Upload the sdist, wheels, and provenance to a GitHub release. They remain
-    # available as build artifacts for a while as well.
     needs: [provenance]
     runs-on: ubuntu-latest
     permissions:
@@ -54,8 +50,6 @@ jobs:
           GH_TOKEN: ${{ github.token }}
   publish-pypi:
     needs: [provenance]
-    # Wait for approval before attempting to upload to PyPI. This allows reviewing the
-    # files in the draft release.
     environment:
       name: publish
       url: https://pypi.org/project/click/${{ github.ref_name }}

.github/workflows/tests.yaml

@@ -1,10 +1,10 @@
 name: Tests
 on:
+  pull_request:
+    paths-ignore: ['docs/**', 'README.md']
   push:
     branches: [main, stable]
-    paths-ignore: ['docs/**', '*.md', '*.rst']
-  pull_request:
-    paths-ignore: [ 'docs/**', '*.md', '*.rst' ]
+    paths-ignore: ['docs/**', 'README.md']
 jobs:
   tests:
     name: ${{ matrix.name || matrix.python }}
@@ -14,35 +14,36 @@ jobs:
       matrix:
         include:
           - {python: '3.13'}
+          - {name: Windows, python: '3.13', os: windows-latest}
+          - {name: Mac, python: '3.13', os: macos-latest}
           - {python: '3.12'}
-          - {name: Windows, python: '3.12', os: windows-latest}
-          - {name: Mac, python: '3.12', os: macos-latest}
           - {python: '3.11'}
           - {python: '3.10'}
-          - {name: PyPy, python: 'pypy-3.11', tox: pypy311}
+          - {name: PyPy, python: 'pypy-3.11', tox: pypy3.11}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0.1
+        with:
+          enable-cache: true
+          prune-cache: false
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: ${{ matrix.python }}
-          allow-prereleases: true
-          cache: pip
-          cache-dependency-path: requirements*/*.txt
-      - run: pip install tox
-      - run: tox run -e ${{ matrix.tox || format('py{0}', matrix.python) }}
+      - run: uv run --locked tox run -e ${{ matrix.tox || format('py{0}', matrix.python) }}
   typing:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0.1
+        with:
+          enable-cache: true
+          prune-cache: false
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
-          python-version: '3.x'
-          cache: pip
-          cache-dependency-path: requirements*/*.txt
+          python-version-file: pyproject.toml
       - name: cache mypy
         uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
         with:
           path: ./.mypy_cache
           key: mypy|${{ hashFiles('pyproject.toml') }}
-      - run: pip install tox
-      - run: tox run -e typing
+      - run: uv run --locked tox run -e typing

.gitignore

@@ -1,9 +1,5 @@
 .idea/
 .vscode/
-.venv*/
-venv*/
-.env*/
-env*/
 __pycache__/
 dist/
 .coverage*

.pre-commit-config.yaml

@@ -1,11 +1,15 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.9
+    rev: 24e02b24b8ab2b7c76225602d13fa60e12d114e6  # frozen: v0.11.9
     hooks:
       - id: ruff
       - id: ruff-format
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 14ac15b122e538e407d036ff45e3895b7cf4a2bf  # frozen: 0.7.3
+    hooks:
+      - id: uv-lock
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b  # frozen: v5.0.0
     hooks:
       - id: check-merge-conflict
       - id: debug-statements

.readthedocs.yaml

@@ -1,14 +1,10 @@
 version: 2
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: '3.12'
-python:
-  install:
-    - requirements: requirements/docs.txt
-    - method: pip
-      path: .
-sphinx:
-  builder: dirhtml
-  configuration: docs/conf.py
-  fail_on_warning: true
+    python: '3.13'
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv run --group docs sphinx-build -W -b dirhtml docs $READTHEDOCS_OUTPUT/html

pyproject.toml

@@ -21,10 +21,42 @@ dependencies = [
 [project.urls]
 Donate = "https://palletsprojects.com/donate"
 Documentation = "https://click.palletsprojects.com/"
-Changes = "https://click.palletsprojects.com/changes/"
+Changes = "https://click.palletsprojects.com/page/changes/"
 Source = "https://github.com/pallets/click/"
 Chat = "https://discord.gg/pallets"
 
+[dependency-groups]
+dev = [
+    "ruff",
+    "tox",
+    "tox-uv",
+]
+docs = [
+    "myst-parser",
+    "pallets-sphinx-themes",
+    "sphinx",
+    "sphinx-tabs",
+    "sphinxcontrib-log-cabinet",
+]
+docs-auto = [
+    "sphinx-autobuild",
+]
+gha-update = [
+    "gha-update ; python_full_version >= '3.12'",
+]
+pre-commit = [
+    "pre-commit",
+    "pre-commit-uv",
+]
+tests = [
+    "pytest",
+]
+typing = [
+    "mypy",
+    "pyright",
+    "pytest",
+]
+
 [build-system]
 requires = ["flit_core<4"]
 build-backend = "flit_core.buildapi"
@@ -35,15 +67,17 @@ name = "click"
 [tool.flit.sdist]
 include = [
     "docs/",
-    "requirements/",
     "tests/",
     "CHANGES.rst",
-    "tox.ini",
+    "uv.lock"
 ]
 exclude = [
     "docs/_build/",
 ]
 
+[tool.uv]
+default-groups = ["dev", "pre-commit", "tests", "typing"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 filterwarnings = [
@@ -57,9 +91,16 @@ source = ["click", "tests"]
 [tool.coverage.paths]
 source = ["src", "*/site-packages"]
 
+[tool.coverage.report]
+exclude_also = [
+    "if t.TYPE_CHECKING",
+    "raise NotImplementedError",
+    ": \\.{3}",
+]
+
 [tool.mypy]
 python_version = "3.10"
-files = ["src/click", "tests/typing"]
+files = ["src", "tests/typing"]
 show_error_codes = true
 pretty = true
 strict = true
@@ -72,7 +113,7 @@ ignore_missing_imports = true
 
 [tool.pyright]
 pythonVersion = "3.10"
-include = ["src/click", "tests/typing"]
+include = ["src", "tests/typing"]
 typeCheckingMode = "basic"
 
 [tool.ruff]
@@ -92,7 +133,7 @@ select = [
     "W",  # pycodestyle warning
 ]
 ignore = [
-    "UP038",  # keep isinstance tuples
+    "UP038",  # keep isinstance tuple
 ]
 
 [tool.ruff.lint.isort]
@@ -103,3 +144,70 @@ order-by-type = false
 tag-only = [
     "slsa-framework/slsa-github-generator",
 ]
+
+[tool.tox]
+env_list = [
+    "py3.13", "py3.12", "py3.11", "py3.10",
+    "pypy3.11",
+    "style",
+    "typing",
+    "docs",
+]
+
+[tool.tox.env_run_base]
+description = "pytest on latest dependency versions"
+runner = "uv-venv-lock-runner"
+package = "wheel"
+wheel_build_env = ".pkg"
+constrain_package_deps = true
+use_frozen_constraints = true
+dependency_groups = ["tests"]
+commands = [[
+    "pytest", "-v", "--tb=short", "--basetemp={env_tmp_dir}",
+    {replace = "posargs", default = [], extend = true},
+]]
+
+[tool.tox.env.style]
+description = "run all pre-commit hooks on all files"
+dependency_groups = ["pre-commit"]
+skip_install = true
+commands = [["pre-commit", "run", "--all-files"]]
+
+[tool.tox.env.typing]
+description = "run static type checkers"
+dependency_groups = ["typing"]
+commands = [
+    ["mypy"],
+]
+
+[tool.tox.env.docs]
+description = "build docs"
+dependency_groups = ["docs"]
+commands = [["sphinx-build", "-E", "-W", "-b", "dirhtml", "docs", "docs/_build/dirhtml"]]
+
+[tool.tox.env.docs-auto]
+description = "continuously rebuild docs and start a local server"
+dependency_groups = ["docs", "docs-auto"]
+commands = [["sphinx-autobuild", "-W", "-b", "dirhtml", "--watch", "src", "docs", "docs/_build/dirhtml"]]
+
+[tool.tox.env.update-actions]
+description = "update GitHub Actions pins"
+labels = ["update"]
+dependency_groups = ["gha-update"]
+skip_install = true
+commands = [["gha-update"]]
+
+[tool.tox.env.update-pre_commit]
+description = "update pre-commit pins"
+labels = ["update"]
+dependency_groups = ["pre-commit"]
+skip_install = true
+commands = [["pre-commit", "autoupdate", "--freeze", "-j4"]]
+
+[tool.tox.env.update-requirements]
+description = "update uv lock"
+labels = ["update"]
+dependency_groups = []
+no_default_groups = true
+skip_install = true
+commands = [["uv", "lock", {replace = "posargs", default = ["-U"], extend = true}]]