Merge branch 'main' into psfgh-3545

.github/ISSUE_TEMPLATE/bug_report.md

@@ -12,7 +12,9 @@ current development version. To confirm this, you have three options:
 
 1. Update Black's version if a newer release exists: `pip install -U black`
 2. Use the online formatter at <https://black.vercel.app/?version=main>, which will use
-   the latest main branch.
+   the latest main branch. Note that the online formatter currently runs on
+   an older version of Python and may not support newer syntax, such as the
+   extended f-string syntax added in Python 3.12.
 3. Or run _Black_ on your machine:
    - create a new virtualenv (make sure it's the same Python version);
    - clone this repository;

.github/workflows/pypi_upload.yml

@@ -89,7 +89,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: pypa/cibuildwheel@v2.17.0
+      - uses: pypa/cibuildwheel@v2.18.1
         with:
           only: ${{ matrix.only }}
 

.github/workflows/test.yml

@@ -62,7 +62,7 @@ jobs:
         if:
           github.repository == 'psf/black' && matrix.os == 'ubuntu-latest' &&
           !startsWith(matrix.python-version, 'pypy')
-        uses: AndreMiras/coveralls-python-action@8799c9f4443ac4201d2e2f2c725d577174683b99
+        uses: AndreMiras/coveralls-python-action@65c1672f0b8a201702d86c81b79187df74072505
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           parallel: true
@@ -77,7 +77,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Send finished signal to Coveralls
-        uses: AndreMiras/coveralls-python-action@8799c9f4443ac4201d2e2f2c725d577174683b99
+        uses: AndreMiras/coveralls-python-action@65c1672f0b8a201702d86c81b79187df74072505
         with:
           parallel-finished: true
           debug: true

AUTHORS.md

@@ -181,6 +181,7 @@ Multiple contributions by:
 - [Tony Narlock](mailto:tony@git-pull.com)
 - [Tsuyoshi Hombashi](mailto:tsuyoshi.hombashi@gmail.com)
 - [Tushar Chandra](mailto:tusharchandra2018@u.northwestern.edu)
+- [Tushar Sadhwani](mailto:tushar.sadhwani000@gmail.com)
 - [Tzu-ping Chung](mailto:uranusjr@gmail.com)
 - [Utsav Shah](mailto:ukshah2@illinois.edu)
 - utsav-dbx

CHANGES.md

@@ -6,13 +6,11 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
-- Add support for the new Python 3.12 f-string syntax introduced by PEP 701 (#3822)
-
 ### Stable style
 
 <!-- Changes that affect Black's stable style -->
 
-- Fix crash involving indented dummy functions containing newlines (#4318)
+- Fix crash when `# fmt: off` is used before a closing parenthesis or bracket. (#4363)
 
 ### Preview style
 
@@ -28,10 +26,18 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Packaging metadata updated: docs are explictly linked, the issue tracker is now also
+  linked. This improves the PyPI listing for Black. (#4345)
+
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
 
+- Fix regression where Black failed to parse a multiline f-string containing another
+  multiline string (#4339)
+
+- Fix bug with Black incorrectly parsing empty lines with a backslash (#4343)
+
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
@@ -42,19 +48,49 @@
 
 ### _Blackd_
 
-<!-- Changes to blackd -->
+- Fix blackd (and all extras installs) for docker container (#4357)
 
 ### Integrations
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
-- Github Action now works even when `git archive` is skipped (#4313)
-
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+## 24.4.2
+
+This is a bugfix release to fix two regressions in the new f-string parser introduced in
+24.4.1.
+
+### Parser
+
+- Fix regression where certain complex f-strings failed to parse (#4332)
+
+### Performance
+
+- Fix bad performance on certain complex string literals (#4331)
+
+## 24.4.1
+
+### Highlights
+
+- Add support for the new Python 3.12 f-string syntax introduced by PEP 701 (#3822)
+
+### Stable style
+
+- Fix crash involving indented dummy functions containing newlines (#4318)
+
+### Parser
+
+- Add support for type parameter defaults, a new syntactic feature added to Python 3.13
+  by PEP 696 (#4327)
+
+### Integrations
+
+- Github Action now works even when `git archive` is skipped (#4313)
+
 ## 24.4.0
 
 ### Stable style

Dockerfile

@@ -10,7 +10,8 @@ RUN python -m venv $VIRTUAL_ENV
 RUN python -m pip install --no-cache-dir hatch hatch-fancy-pypi-readme hatch-vcs
 RUN . /opt/venv/bin/activate && pip install --no-cache-dir --upgrade pip setuptools \
     && cd /src && hatch build -t wheel \
-    && pip install --no-cache-dir dist/*-cp*[colorama,d,uvloop]
+    && pip install --no-cache-dir dist/*-cp* \
+    && pip install black[colorama,d,uvloop]
 
 FROM python:3.12-slim
 

docs/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
 #
@@ -14,22 +13,46 @@
 #
 
 import os
+import re
 import string
 from importlib.metadata import version
 from pathlib import Path
 
+from sphinx.application import Sphinx
+
 CURRENT_DIR = Path(__file__).parent
 
 
 def make_pypi_svg(version: str) -> None:
     template: Path = CURRENT_DIR / "_static" / "pypi_template.svg"
     target: Path = CURRENT_DIR / "_static" / "pypi.svg"
-    with open(str(template), "r", encoding="utf8") as f:
+    with open(str(template), encoding="utf8") as f:
         svg: str = string.Template(f.read()).substitute(version=version)
     with open(str(target), "w", encoding="utf8") as f:
         f.write(svg)
 
 
+def replace_pr_numbers_with_links(content: str) -> str:
+    """Replaces all PR numbers with the corresponding GitHub link."""
+    return re.sub(r"#(\d+)", r"[#\1](https://github.com/psf/black/pull/\1)", content)
+
+
+def handle_include_read(
+    app: Sphinx,
+    relative_path: Path,
+    parent_docname: str,
+    content: list[str],
+) -> None:
+    """Handler for the include-read sphinx event."""
+    if parent_docname == "change_log":
+        content[0] = replace_pr_numbers_with_links(content[0])
+
+
+def setup(app: Sphinx) -> None:
+    """Sets up a minimal sphinx extension."""
+    app.connect("include-read", handle_include_read)
+
+
 # Necessary so Click doesn't hit an encode error when called by
 # sphinxcontrib-programoutput on Windows.
 os.putenv("pythonioencoding", "utf-8")

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.4.0
+    rev: 24.4.2
     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.4.0
+    rev: 24.4.2
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python

docs/requirements.txt

@@ -1,9 +1,9 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-myst-parser==2.0.0
+myst-parser==3.0.1
 Sphinx==7.3.7
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.20.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.2
-furo==2024.1.29
+furo==2024.5.6

docs/usage_and_configuration/the_basics.md

@@ -269,8 +269,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 24.4.0 (compiled: yes)
-$ black --required-version 24.4.0 -c "format = 'this'"
+black, 24.4.2 (compiled: yes)
+$ black --required-version 24.4.2 -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.4.0
+black, 24.4.2
 ```
 
 #### `--config`

pyproject.toml

@@ -12,9 +12,10 @@ include = '\.pyi?$'
 extend-exclude = '''
 /(
   # The following are specific to Black, you probably don't want those.
-  tests/data
-  | profiling
-)/
+  tests/data/
+  | profiling/
+  | scripts/generate_schema.py  # Uses match syntax
+)
 '''
 # We use the unstable style for formatting Black itself. If you
 # want bug-free formatting, you should keep this off. If you want
@@ -93,8 +94,10 @@ blackd = "blackd:patched_main [d]"
 black = "black.schema:get_schema"
 
 [project.urls]
+Documentation = "https://black.readthedocs.io/"
 Changelog = "https://github.com/psf/black/blob/main/CHANGES.md"
-Homepage = "https://github.com/psf/black"
+Repository = "https://github.com/psf/black"
+Issues = "https://github.com/psf/black/issues"
 
 [tool.hatch.metadata.hooks.fancy-pypi-readme]
 content-type = "text/markdown"

scripts/diff_shades_gha_helper.py

@@ -24,17 +24,12 @@
 from base64 import b64encode
 from io import BytesIO
 from pathlib import Path
-from typing import Any
+from typing import Any, Final, Literal
 
 import click
 import urllib3
 from packaging.version import Version
 
-if sys.version_info >= (3, 8):
-    from typing import Final, Literal
-else:
-    from typing_extensions import Final, Literal
-
 COMMENT_FILE: Final = ".pr-comment.json"
 DIFF_STEP_NAME: Final = "Generate HTML diff report"
 DOCS_URL: Final = (

scripts/migrate-black.py

@@ -9,7 +9,7 @@
 
 
 def git(*args: str) -> str:
-    return check_output(["git"] + list(args)).decode("utf8").strip()
+    return check_output(["git", *args]).decode("utf8").strip()
 
 
 def blackify(base_branch: str, black_command: str, logger: logging.Logger) -> int:
@@ -26,19 +26,19 @@ def blackify(base_branch: str, black_command: str, logger: logging.Logger) -> in
     merge_base = git("merge-base", "HEAD", base_branch)
     if not merge_base:
         logger.error(
-            "Could not find a common commit for current head and %s" % base_branch
+            f"Could not find a common commit for current head and {base_branch}"
         )
         return 1
 
     commits = git(
-        "log", "--reverse", "--pretty=format:%H", "%s~1..HEAD" % merge_base
+        "log", "--reverse", "--pretty=format:%H", f"{merge_base}~1..HEAD"
     ).split()
     for commit in commits:
-        git("checkout", commit, "-b%s-black" % commit)
+        git("checkout", commit, f"-b{commit}-black")
         check_output(black_command, shell=True)
         git("commit", "-aqm", "blackify")
 
-    git("checkout", base_branch, "-b%s-black" % current_branch)
+    git("checkout", base_branch, f"-b{current_branch}-black")
 
     for last_commit, commit in zip(commits, commits[1:]):
         allow_empty = (
@@ -51,7 +51,7 @@ def blackify(base_branch: str, black_command: str, logger: logging.Logger) -> in
                 "diff",
                 "--binary",
                 "--find-copies",
-                "%s-black..%s-black" % (last_commit, commit),
+                f"{last_commit}-black..{commit}-black",
             ],
             stdout=PIPE,
         )

scripts/release.py

@@ -11,8 +11,7 @@
 import sys
 from datetime import datetime
 from pathlib import Path
-from subprocess import PIPE, run
-from typing import List
+from subprocess import run
 
 LOG = logging.getLogger(__name__)
 NEW_VERSION_CHANGELOG_TEMPLATE = """\
@@ -70,9 +69,9 @@ class NoGitTagsError(Exception): ...  # noqa: E701,E761
 
 # TODO: Do better with alpha + beta releases
 # Maybe we vendor packaging library
-def get_git_tags(versions_only: bool = True) -> List[str]:
+def get_git_tags(versions_only: bool = True) -> list[str]:
     """Pull out all tags or calvers only"""
-    cp = run(["git", "tag"], stdout=PIPE, stderr=PIPE, check=True, encoding="utf8")
+    cp = run(["git", "tag"], capture_output=True, check=True, encoding="utf8")
     if not cp.stdout:
         LOG.error(f"Returned no git tags stdout: {cp.stderr}")
         raise NoGitTagsError

src/black/__init__.py

@@ -1436,6 +1436,12 @@ def get_features_used(  # noqa: C901
         elif n.type in (syms.type_stmt, syms.typeparams):
             features.add(Feature.TYPE_PARAMS)
 
+        elif (
+            n.type in (syms.typevartuple, syms.paramspec, syms.typevar)
+            and n.children[-2].type == token.EQUAL
+        ):
+            features.add(Feature.TYPE_PARAM_DEFAULTS)
+
     return features