Merge branch 'main' into main

.pre-commit-config.yaml

@@ -39,7 +39,7 @@ repos:
         exclude: ^src/blib2to3/
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.2
+    rev: v1.12.0
     hooks:
       - id: mypy
         exclude: ^(docs/conf.py|scripts/generate_schema.py)$

CONTRIBUTING.md

@@ -1,10 +1,13 @@
 # Contributing to _Black_
 
-Welcome! Happy to see you willing to make the project better. Have you read the entire
-[user documentation](https://black.readthedocs.io/en/latest/) yet?
+Welcome future contributor! We're happy to see you willing to make the project better.
 
-Our [contributing documentation](https://black.readthedocs.org/en/latest/contributing/)
-contains details on all you need to know about contributing to _Black_, the basics to
-the internals of _Black_.
+If you aren't familiar with _Black_, or are looking for documentation on something
+specific, the [user documentation](https://black.readthedocs.io/en/latest/) is the best
+place to look.
 
-We look forward to your contributions!
+For getting started on contributing, please read the
+[contributing documentation](https://black.readthedocs.org/en/latest/contributing/) for
+all you need to know.
+
+Thank you, and we look forward to your contributions!

docs/contributing/the_basics.md

@@ -7,7 +7,14 @@ An overview on contributing to the _Black_ project.
 Development on the latest version of Python is preferred. You can use any operating
 system.
 
-Install development dependencies inside a virtual environment of your choice, for
+First clone the _Black_ repository:
+
+```console
+$ git clone https://github.com/psf/black.git
+$ cd black
+```
+
+Then install development dependencies inside a virtual environment of your choice, for
 example:
 
 ```console
@@ -48,13 +55,16 @@ Further examples of invoking the tests
 # Run tests on a specific python version
 (.venv)$ tox -e py39
 
-# pass arguments to pytest
+# Run an individual test
+(.venv)$ pytest -k <test name>
+
+# Pass arguments to pytest
 (.venv)$ tox -e py -- --no-cov
 
-# print full tree diff, see documentation below
+# Print full tree diff, see documentation below
 (.venv)$ tox -e py -- --print-full-tree
 
-# disable diff printing, see documentation below
+# Disable diff printing, see documentation below
 (.venv)$ tox -e py -- --print-tree-diff=False
 ```
 
@@ -99,42 +109,48 @@ default. To turn it off pass `--print-tree-diff=False`.
 `Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
 you feel this PR does not require a changelog entry please state that in a comment and a
 maintainer can add a `skip news` label to make the CI pass. Otherwise, please ensure you
-have a line in the following format:
+have a line in the following format added below the appropriate header:
 
 ```md
 - `Black` is now more awesome (#X)
 ```
 
+<!---
+The Next PR Number link uses HTML because of a bug in MyST-Parser that double-escapes the ampersand, causing the query parameters to not be processed.
+MyST-Parser issue: https://github.com/executablebooks/MyST-Parser/issues/760
+MyST-Parser stalled fix PR: https://github.com/executablebooks/MyST-Parser/pull/929
+-->
+
 Note that X should be your PR number, not issue number! To workout X, please use
-[Next PR Number](https://ichard26.github.io/next-pr-number/?owner=psf&name=black). This
-is not perfect but saves a lot of release overhead as now the releaser does not need to
-go back and workout what to add to the `CHANGES.md` for each release.
+<a href="https://ichard26.github.io/next-pr-number/?owner=psf&name=black">Next PR
+Number</a>. This is not perfect but saves a lot of release overhead as now the releaser
+does not need to go back and workout what to add to the `CHANGES.md` for each release.
 
 ### Style Changes
 
 If a change would affect the advertised code style, please modify the documentation (The
 _Black_ code style) to reflect that change. Patches that fix unintended bugs in
 formatting don't need to be mentioned separately though. If the change is implemented
 with the `--preview` flag, please include the change in the future style document
-instead and write the changelog entry under a dedicated "Preview changes" heading.
+instead and write the changelog entry under the dedicated "Preview style" heading.
 
 ### Docs Testing
 
 If you make changes to docs, you can test they still build locally too.
 
 ```console
 (.venv)$ pip install -r docs/requirements.txt
-(.venv)$ pip install -e .[d]
+(.venv)$ pip install -e ".[d]"
 (.venv)$ sphinx-build -a -b html -W docs/ docs/_build/
 ```
 
 ## Hygiene
 
 If you're fixing a bug, add a test. Run it first to confirm it fails, then fix the bug,
-run it again to confirm it's really fixed.
+and run the test again to confirm it's really fixed.
 
-If adding a new feature, add a test. In fact, always add a test. But wait, before adding
-any large feature, first open an issue for us to discuss the idea first.
+If adding a new feature, add a test. In fact, always add a test. If adding a large
+feature, please first open an issue to discuss it beforehand.
 
 ## Finally
 

docs/integrations/github_actions.md

@@ -74,9 +74,14 @@ If you want to match versions covered by Black's
     version: "~= 22.0"
 ```
 
-If you want to read the version from `pyproject.toml`, set `use_pyproject` to `true`:
+If you want to read the version from `pyproject.toml`, set `use_pyproject` to `true`.
+Note that this requires Python >= 3.11, so using the setup-python action may be
+required, for example:
 
 ```yaml
+- uses: actions/setup-python@v5
+  with:
+    python-version: "3.13"
 - uses: psf/black@stable
   with:
     options: "--check --verbose"

gallery/gallery.py

@@ -7,10 +7,11 @@
 import venv
 import zipfile
 from argparse import ArgumentParser, Namespace
+from collections.abc import Generator
 from concurrent.futures import ThreadPoolExecutor
 from functools import lru_cache, partial
 from pathlib import Path
-from typing import Generator, NamedTuple, Optional, Union, cast
+from typing import NamedTuple, Optional, Union, cast
 from urllib.request import urlopen, urlretrieve
 
 PYPI_INSTANCE = "https://pypi.org/pypi"

pyproject.toml

@@ -125,7 +125,7 @@ macos-max-compat = true
 enable-by-default = false
 dependencies = [
   "hatch-mypyc>=0.16.0",
-  "mypy @ git+https://github.com/python/mypy@bc8119150e49895f7a496ae7ae7362a2828e7e9e",
+  "mypy>=1.12",
   "click>=8.1.7",
 ]
 require-runtime-dependencies = true
@@ -192,7 +192,7 @@ build-frontend = { name = "build", args = ["--no-isolation"] }
 # Note we don't have a good test for this sed horror, so if you futz with it
 # make sure to test manually
 before-build = [
-    "python -m pip install 'hatchling==1.20.0' hatch-vcs hatch-fancy-pypi-readme 'hatch-mypyc>=0.16.0' 'mypy @ git+https://github.com/python/mypy@bc8119150e49895f7a496ae7ae7362a2828e7e9e' 'click>=8.1.7'",
+    "python -m pip install 'hatchling==1.20.0' hatch-vcs hatch-fancy-pypi-readme 'hatch-mypyc>=0.16.0' 'mypy>=1.12' 'click>=8.1.7'",
     """sed -i '' -e "600,700s/'10_16'/os.environ['MACOSX_DEPLOYMENT_TARGET'].replace('.', '_')/" $(python -c 'import hatchling.builders.wheel as h; print(h.__file__)') """,
 ]
 

scripts/make_width_table.py

@@ -17,8 +17,8 @@
 """
 
 import sys
+from collections.abc import Iterable
 from os.path import basename, dirname, join
-from typing import Iterable
 
 import wcwidth  # type: ignore[import-not-found]
 

src/black/__init__.py

@@ -5,24 +5,22 @@
 import sys
 import tokenize
 import traceback
-from contextlib import contextmanager
-from dataclasses import replace
-from datetime import datetime, timezone
-from enum import Enum
-from json.decoder import JSONDecodeError
-from pathlib import Path
-from typing import (
-    Any,
+from collections.abc import (
     Collection,
     Generator,
     Iterator,
     MutableMapping,
-    Optional,
-    Pattern,
     Sequence,
     Sized,
-    Union,
 )
+from contextlib import contextmanager
+from dataclasses import replace
+from datetime import datetime, timezone
+from enum import Enum
+from json.decoder import JSONDecodeError
+from pathlib import Path
+from re import Pattern
+from typing import Any, Optional, Union
 
 import click
 from click.core import ParameterSource

src/black/brackets.py

@@ -1,7 +1,8 @@
 """Builds on top of nodes.py to track brackets."""
 
+from collections.abc import Iterable, Sequence
 from dataclasses import dataclass, field
-from typing import Final, Iterable, Optional, Sequence, Union
+from typing import Final, Optional, Union
 
 from black.nodes import (
     BRACKET,

src/black/cache.py

@@ -5,9 +5,10 @@
 import pickle
 import sys
 import tempfile
+from collections.abc import Iterable
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Iterable, NamedTuple
+from typing import NamedTuple
 
 from platformdirs import user_cache_dir
 

src/black/comments.py

@@ -1,7 +1,8 @@
 import re
+from collections.abc import Collection, Iterator
 from dataclasses import dataclass
 from functools import lru_cache
-from typing import Collection, Final, Iterator, Optional, Union
+from typing import Final, Optional, Union
 
 from black.mode import Mode, Preview
 from black.nodes import (

src/black/concurrency.py

@@ -10,10 +10,11 @@
 import signal
 import sys
 import traceback
+from collections.abc import Iterable
 from concurrent.futures import Executor, ProcessPoolExecutor, ThreadPoolExecutor
 from multiprocessing import Manager
 from pathlib import Path
-from typing import Any, Iterable, Optional
+from typing import Any, Optional
 
 from mypy_extensions import mypyc_attr
 

src/black/debug.py

@@ -1,5 +1,6 @@
+from collections.abc import Iterator
 from dataclasses import dataclass, field
-from typing import Any, Iterator, TypeVar, Union
+from typing import Any, TypeVar, Union
 
 from black.nodes import Visitor
 from black.output import out

src/black/files.py

@@ -1,18 +1,11 @@
 import io
 import os
 import sys
+from collections.abc import Iterable, Iterator, Sequence
 from functools import lru_cache
 from pathlib import Path
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Iterable,
-    Iterator,
-    Optional,
-    Pattern,
-    Sequence,
-    Union,
-)
+from re import Pattern
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 from mypy_extensions import mypyc_attr
 from packaging.specifiers import InvalidSpecifier, Specifier, SpecifierSet

src/black/linegen.py

@@ -4,10 +4,11 @@
 
 import re
 import sys
+from collections.abc import Collection, Iterator
 from dataclasses import replace
 from enum import Enum, auto
 from functools import partial, wraps
-from typing import Collection, Iterator, Optional, Union, cast
+from typing import Optional, Union, cast
 
 from black.brackets import (
     COMMA_PRIORITY,

src/black/lines.py

@@ -1,7 +1,8 @@
 import itertools
 import math
+from collections.abc import Callable, Iterator, Sequence
 from dataclasses import dataclass, field
-from typing import Callable, Iterator, Optional, Sequence, TypeVar, Union, cast
+from typing import Optional, TypeVar, Union, cast
 
 from black.brackets import COMMA_PRIORITY, DOT_PRIORITY, BracketTracker
 from black.mode import Mode, Preview

src/black/nodes.py

@@ -3,7 +3,8 @@
 """
 
 import sys
-from typing import Final, Generic, Iterator, Literal, Optional, TypeVar, Union
+from collections.abc import Iterator
+from typing import Final, Generic, Literal, Optional, TypeVar, Union
 
 if sys.version_info >= (3, 10):
     from typing import TypeGuard

src/black/parsing.py

@@ -5,7 +5,7 @@
 import ast
 import sys
 import warnings
-from typing import Collection, Iterator
+from collections.abc import Collection, Iterator
 
 from black.mode import VERSION_TO_FEATURES, Feature, TargetVersion, supports_feature
 from black.nodes import syms

src/black/ranges.py

@@ -1,8 +1,9 @@
 """Functions related to Black's formatting by line ranges feature."""
 
 import difflib
+from collections.abc import Collection, Iterator, Sequence
 from dataclasses import dataclass
-from typing import Collection, Iterator, Sequence, Union
+from typing import Union
 
 from black.nodes import (
     LN,

src/black/strings.py

@@ -5,7 +5,8 @@
 import re
 import sys
 from functools import lru_cache
-from typing import Final, Match, Pattern
+from re import Match, Pattern
+from typing import Final
 
 from black._width_table import WIDTH_TABLE
 from blib2to3.pytree import Leaf

src/black/trans.py

@@ -5,21 +5,9 @@
 import re
 from abc import ABC, abstractmethod
 from collections import defaultdict
+from collections.abc import Callable, Collection, Iterable, Iterator, Sequence
 from dataclasses import dataclass
-from typing import (
-    Any,
-    Callable,
-    ClassVar,
-    Collection,
-    Final,
-    Iterable,
-    Iterator,
-    Literal,
-    Optional,
-    Sequence,
-    TypeVar,
-    Union,
-)
+from typing import Any, ClassVar, Final, Literal, Optional, TypeVar, Union
 
 from mypy_extensions import trait
 

src/blackd/middlewares.py

@@ -1,4 +1,4 @@
-from typing import Awaitable, Callable, Iterable
+from collections.abc import Awaitable, Callable, Iterable
 
 from aiohttp.typedefs import Middleware
 from aiohttp.web_middlewares import middleware

src/blib2to3/pgen2/driver.py

@@ -21,10 +21,11 @@
 import os
 import pkgutil
 import sys
+from collections.abc import Iterable, Iterator
 from contextlib import contextmanager
 from dataclasses import dataclass, field
 from logging import Logger
-from typing import IO, Any, Iterable, Iterator, Optional, Union, cast
+from typing import IO, Any, Optional, Union, cast
 
 from blib2to3.pgen2.grammar import Grammar
 from blib2to3.pgen2.tokenize import GoodTokenInfo