Merge branch 'main' of https://github.com/psf/black into psfgh-3545

.github/workflows/diff_shades_comment.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Try to find pre-existing PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
-        uses: peter-evans/find-comment@d5fe37641ad8451bdd80312415672ba26c86575e
+        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e
         with:
           issue-number: ${{ steps.metadata.outputs.pr-number }}
           comment-author: "github-actions[bot]"

.github/workflows/doc.yml

@@ -30,9 +30,9 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip setuptools wheel
-          python -m pip install -e ".[d]"
-          python -m pip install -r "docs/requirements.txt"
+          python -m pip install uv
+          python -m uv pip install --system -e ".[d]"
+          python -m uv pip install --system -r "docs/requirements.txt"
 
       - name: Build documentation
         run: sphinx-build -a -b html -W --keep-going docs/ docs/_build

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
       - id: isort
 
   - repo: https://github.com/pycqa/flake8
-    rev: 6.1.0
+    rev: 7.0.0
     hooks:
       - id: flake8
         additional_dependencies:
@@ -39,7 +39,7 @@ repos:
         exclude: ^src/blib2to3/
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.8.0
+    rev: v1.9.0
     hooks:
       - id: mypy
         exclude: ^(docs/conf.py|scripts/generate_schema.py)$

CHANGES.md

@@ -10,16 +10,10 @@
 
 <!-- Changes that affect Black's stable style -->
 
-- Fix unwanted crashes caused by AST equivalency check (#4290)
-
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
 
-- `if` guards in `case` blocks are now wrapped in parentheses when the line is too long.
-  (#4269)
-- Stop moving multiline strings to a new line unless inside brackets (#4289)
-
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
@@ -53,6 +47,23 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+## 24.4.0
+
+### Stable style
+
+- Fix unwanted crashes caused by AST equivalency check (#4290)
+
+### Preview style
+
+- `if` guards in `case` blocks are now wrapped in parentheses when the line is too long.
+  (#4269)
+- Stop moving multiline strings to a new line unless inside brackets (#4289)
+
+### Integrations
+
+- Add a new option `use_pyproject` to the GitHub Action `psf/black`. This will read the
+  Black version from `pyproject.toml`. (#4294)
+
 ## 24.3.0
 
 ### Highlights

action.yml

@@ -27,6 +27,10 @@ inputs:
     description: 'Python Version specifier (PEP440) - e.g. "21.5b1"'
     required: false
     default: ""
+  use_pyproject:
+    description: Read Black version specifier from pyproject.toml if `true`.
+    required: false
+    default: "false"
   summary:
     description: "Whether to add the output to the workflow summary"
     required: false
@@ -70,5 +74,6 @@ runs:
         INPUT_JUPYTER: ${{ inputs.jupyter }}
         INPUT_BLACK_ARGS: ${{ inputs.black_args }}
         INPUT_VERSION: ${{ inputs.version }}
+        INPUT_USE_PYPROJECT: ${{ inputs.use_pyproject }}
         pythonioencoding: utf-8
       shell: bash

action/main.py

@@ -1,9 +1,11 @@
 import os
+import re
 import shlex
 import shutil
 import sys
 from pathlib import Path
 from subprocess import PIPE, STDOUT, run
+from typing import Union
 
 ACTION_PATH = Path(os.environ["GITHUB_ACTION_PATH"])
 ENV_PATH = ACTION_PATH / ".black-env"
@@ -13,12 +15,107 @@
 JUPYTER = os.getenv("INPUT_JUPYTER") == "true"
 BLACK_ARGS = os.getenv("INPUT_BLACK_ARGS", default="")
 VERSION = os.getenv("INPUT_VERSION", default="")
+USE_PYPROJECT = os.getenv("INPUT_USE_PYPROJECT") == "true"
+
+BLACK_VERSION_RE = re.compile(r"^black([^A-Z0-9._-]+.*)$", re.IGNORECASE)
+EXTRAS_RE = re.compile(r"\[.*\]")
+
+
+def determine_version_specifier() -> str:
+    """Determine the version of Black to install.
+
+    The version can be specified either via the `with.version` input or via the
+    pyproject.toml file if `with.use_pyproject` is set to `true`.
+    """
+    if USE_PYPROJECT and VERSION:
+        print(
+            "::error::'with.version' and 'with.use_pyproject' inputs are "
+            "mutually exclusive.",
+            file=sys.stderr,
+            flush=True,
+        )
+        sys.exit(1)
+    if USE_PYPROJECT:
+        return read_version_specifier_from_pyproject()
+    elif VERSION and VERSION[0] in "0123456789":
+        return f"=={VERSION}"
+    else:
+        return VERSION
+
+
+def read_version_specifier_from_pyproject() -> str:
+    if sys.version_info < (3, 11):
+        print(
+            "::error::'with.use_pyproject' input requires Python 3.11 or later.",
+            file=sys.stderr,
+            flush=True,
+        )
+        sys.exit(1)
+
+    import tomllib  # type: ignore[import-not-found,unreachable]
+
+    try:
+        with Path("pyproject.toml").open("rb") as fp:
+            pyproject = tomllib.load(fp)
+    except FileNotFoundError:
+        print(
+            "::error::'with.use_pyproject' input requires a pyproject.toml file.",
+            file=sys.stderr,
+            flush=True,
+        )
+        sys.exit(1)
+
+    version = pyproject.get("tool", {}).get("black", {}).get("required-version")
+    if version is not None:
+        return f"=={version}"
+
+    arrays = [
+        pyproject.get("project", {}).get("dependencies"),
+        *pyproject.get("project", {}).get("optional-dependencies", {}).values(),
+    ]
+    for array in arrays:
+        version = find_black_version_in_array(array)
+        if version is not None:
+            break
+
+    if version is None:
+        print(
+            "::error::'black' dependency missing from pyproject.toml.",
+            file=sys.stderr,
+            flush=True,
+        )
+        sys.exit(1)
+
+    return version
+
+
+def find_black_version_in_array(array: object) -> Union[str, None]:
+    if not isinstance(array, list):
+        return None
+    try:
+        for item in array:
+            # Rudimentary PEP 508 parsing.
+            item = item.split(";")[0]
+            item = EXTRAS_RE.sub("", item).strip()
+            if item == "black":
+                print(
+                    "::error::Version specifier missing for 'black' dependency in "
+                    "pyproject.toml.",
+                    file=sys.stderr,
+                    flush=True,
+                )
+                sys.exit(1)
+            elif m := BLACK_VERSION_RE.match(item):
+                return m.group(1).strip()
+    except TypeError:
+        pass
+
+    return None
+
 
 run([sys.executable, "-m", "venv", str(ENV_PATH)], check=True)
 
-version_specifier = VERSION
-if VERSION and VERSION[0] in "0123456789":
-    version_specifier = f"=={VERSION}"
+version_specifier = determine_version_specifier()
 if JUPYTER:
     extra_deps = "[colorama,jupyter]"
 else:

docs/getting_started.md

@@ -19,6 +19,8 @@ Also, you can try out _Black_ online for minimal fuss on the
 _Black_ can be installed by running `pip install black`. It requires Python 3.8+ to run.
 If you want to format Jupyter Notebooks, install with `pip install "black[jupyter]"`.
 
+If you use pipx, you can install Black with `pipx install black`.
+
 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
 
 `pip install git+https://github.com/psf/black`

docs/integrations/github_actions.md

@@ -32,12 +32,15 @@ We recommend the use of the `@stable` tag, but per version tags also exist if yo
 that. Note that the action's version you select is independent of the version of _Black_
 the action will use.
 
-The version of _Black_ the action will use can be configured via `version`. This can be
-any
+The version of _Black_ the action will use can be configured via `version` or read from
+the `pyproject.toml` file. `version` can be any
 [valid version specifier](https://packaging.python.org/en/latest/glossary/#term-Version-Specifier)
-or just the version number if you want an exact version. The action defaults to the
-latest release available on PyPI. Only versions available from PyPI are supported, so no
-commit SHAs or branch names.
+or just the version number if you want an exact version. To read the version from the
+`pyproject.toml` file instead, set `use_pyproject` to `true`. This will first look into
+the `tool.black.required-version` field, then the `project.dependencies` array and
+finally the `project.optional-dependencies` table. The action defaults to the latest
+release available on PyPI. Only versions available from PyPI are supported, so no commit
+SHAs or branch names.
 
 If you want to include Jupyter Notebooks, _Black_ must be installed with the `jupyter`
 extra. Installing the extra and including Jupyter Notebook files can be configured via
@@ -70,3 +73,13 @@ If you want to match versions covered by Black's
     src: "./src"
     version: "~= 22.0"
 ```
+
+If you want to read the version from `pyproject.toml`, set `use_pyproject` to `true`:
+
+```yaml
+- uses: psf/black@stable
+  with:
+    options: "--check --verbose"
+    src: "./src"
+    use_pyproject: true
+```

docs/integrations/source_version_control.md

@@ -8,7 +8,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 repos:
   # Using this mirror lets us use mypyc-compiled black, which is about 2x faster
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.3.0
+    rev: 24.4.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
@@ -35,7 +35,7 @@ include Jupyter Notebooks. To use this hook, simply replace the hook's `id: blac
 repos:
   # Using this mirror lets us use mypyc-compiled black, which is about 2x faster
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.3.0
+    rev: 24.4.0
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python

docs/the_black_code_style/future_style.md

@@ -35,7 +35,7 @@ Currently, the following features are included in the preview style:
 - `remove_redundant_guard_parens`: Removes redundant parentheses in `if` guards for
   `case` blocks.
 - `parens_for_long_if_clauses_in_case_block`: Adds parentheses to `if` clauses in `case`
-  blocks when the the line is too long
+  blocks when the line is too long
 
 (labels/unstable-features)=
 

docs/usage_and_configuration/the_basics.md

@@ -269,8 +269,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 24.3.0 (compiled: yes)
-$ black --required-version 24.3.0 -c "format = 'this'"
+black, 24.4.0 (compiled: yes)
+$ black --required-version 24.4.0 -c "format = 'this'"
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!
@@ -366,7 +366,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 24.3.0
+black, 24.4.0
 ```
 
 #### `--config`