Merge branch 'main' into standardize-type-comments

Author: JelleZijlstra

.github/workflows/pypi_upload.yml

@@ -47,9 +47,10 @@ jobs:
       include: ${{ steps.set-matrix.outputs.include }}
     steps:
       - uses: actions/checkout@v4
+      # Keep cibuildwheel version in sync with below
       - name: Install cibuildwheel and pypyp
         run: |
-          pipx install cibuildwheel==2.20.0
+          pipx install cibuildwheel==2.21.2
           pipx install pypyp==1
       - name: generate matrix
         if: github.event_name != 'pull_request'
@@ -74,7 +75,7 @@ jobs:
             | pyp 'json.dumps({"only": x, "os": "ubuntu-latest"})'
           } | pyp 'json.dumps(list(map(json.loads, lines)))' > /tmp/matrix
         env:
-          CIBW_BUILD: "cp39-* cp312-*"
+          CIBW_BUILD: "cp39-* cp313-*"
           CIBW_ARCHS_LINUX: x86_64
       - id: set-matrix
         run: echo "include=$(cat /tmp/matrix)" | tee -a $GITHUB_OUTPUT
@@ -90,14 +91,15 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: pypa/[email protected]
+      # Keep cibuildwheel version in sync with above
+      - uses: pypa/[email protected]
         with:
           only: ${{ matrix.only }}
 
       - name: Upload wheels as workflow artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: ${{ matrix.name }}-mypyc-wheels
+          name: ${{ matrix.only }}-mypyc-wheels
           path: ./wheelhouse/*.whl
 
       - if: github.event_name == 'release'

.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)$

CHANGES.md

@@ -6,34 +6,19 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
-- Black is now officially tested with Python 3.13. Note that Black does not yet provide
-  mypyc-compiled wheels for Python 3.13, so performance may be slower than on other
-  versions of Python. We will provide 3.13 mypyc-compiled wheels in a future release.
-  (#4436)
-- Black will issue an error when used with Python 3.12.5, due to an upstream memory
-  safety issue in Python 3.12.5 that can cause Black's AST safety checks to fail. Please
-  use Python 3.12.6 or Python 3.12.4 instead. (#4447)
-- Black no longer supports running with Python 3.8 (#4452)
-
 ### Stable style
 
 <!-- Changes that affect Black's stable style -->
 
-- Fix crashes involving comments in parenthesised return types or `X | Y` style unions.
-  (#4453)
-- Fix skipping Jupyter cells with unknown `%%` magic (#4462)
+- Fix formatting cells in IPython notebooks with magic methods and starting or trailing
+  empty lines (#4484)
 
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
 
-- Fix type annotation spacing between * and more complex type variable tuple (i.e. `def
-  fn(*args: *tuple[*Ts, T]) -> None: pass`) (#4440)
 - Standardize type comments to always have one space (#4467)
-
-### Caching
-
-- Fix bug where the cache was shared between runs with and without `--unstable` (#4466)
+- Remove parentheses around sole list items (#4312)
 
 ### Configuration
 
@@ -43,8 +28,8 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
-- Upgrade version of mypyc used to 1.11.2 (#4450)
-- `blackd` now requires a newer version of aiohttp. (#4451)
+- Store license identifier inside the `License-Expression` metadata field, see
+  [PEP 639](https://peps.python.org/pep-0639/). (#4479)
 
 ### Parser
 
@@ -58,9 +43,6 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
-- Added Python target version information on parse error (#4378)
-- Add information about Black version to internal error messages (#4457)
-
 ### _Blackd_
 
 <!-- Changes to blackd -->
@@ -74,6 +56,42 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+## 24.10.0
+
+### Highlights
+
+- Black is now officially tested with Python 3.13 and provides Python 3.13
+  mypyc-compiled wheels. (#4436) (#4449)
+- Black will issue an error when used with Python 3.12.5, due to an upstream memory
+  safety issue in Python 3.12.5 that can cause Black's AST safety checks to fail. Please
+  use Python 3.12.6 or Python 3.12.4 instead. (#4447)
+- Black no longer supports running with Python 3.8 (#4452)
+
+### Stable style
+
+- Fix crashes involving comments in parenthesised return types or `X | Y` style unions.
+  (#4453)
+- Fix skipping Jupyter cells with unknown `%%` magic (#4462)
+
+### Preview style
+
+- Fix type annotation spacing between * and more complex type variable tuple (i.e. `def
+  fn(*args: *tuple[*Ts, T]) -> None: pass`) (#4440)
+
+### Caching
+
+- Fix bug where the cache was shared between runs with and without `--unstable` (#4466)
+
+### Packaging
+
+- Upgrade version of mypyc used to 1.12 beta (#4450) (#4449)
+- `blackd` now requires a newer version of aiohttp. (#4451)
+
+### Output
+
+- Added Python target version information on parse error (#4378)
+- Add information about Black version to internal error messages (#4457)
+
 ## 24.8.0
 
 ### Stable style

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!

README.md

@@ -38,7 +38,7 @@ Try it out now using the [Black Playground](https://black.vercel.app). Watch the
 
 ### Installation
 
-_Black_ can be installed by running `pip install black`. It requires Python 3.8+ to run.
+_Black_ can be installed by running `pip install black`. It requires Python 3.9+ to run.
 If you want to format Jupyter Notebooks, install with `pip install "black[jupyter]"`.
 
 If you can't wait for the latest _hotness_ and want to install from GitHub, use:

autoload/black.vim

@@ -76,7 +76,7 @@ def _initialize_black_env(upgrade=False):
 
   pyver = sys.version_info[:3]
   if pyver < (3, 8):
-    print("Sorry, Black requires Python 3.8+ to run.")
+    print("Sorry, Black requires Python 3.9+ to run.")
     return False
 
   from pathlib import Path

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/faq.md

@@ -84,16 +84,17 @@ See [Using _Black_ with other tools](labels/why-pycodestyle-warnings).
 
 ## Which Python versions does Black support?
 
-Currently the runtime requires Python 3.8-3.11. Formatting is supported for files
-containing syntax from Python 3.3 to 3.11. We promise to support at least all Python
-versions that have not reached their end of life. This is the case for both running
-_Black_ and formatting code.
+_Black_ generally supports all Python versions supported by CPython (see
+[the Python devguide](https://devguide.python.org/versions/) for current information).
+We promise to support at least all Python versions that have not reached their end of
+life. This is the case for both running _Black_ and formatting code.
 
 Support for formatting Python 2 code was removed in version 22.0. While we've made no
 plans to stop supporting older Python 3 minor versions immediately, their support might
 also be removed some time in the future without a deprecation period.
 
-Runtime support for 3.7 was removed in version 23.7.0.
+Runtime support for 3.6 was removed in version 22.10.0, for 3.7 in version 23.7.0, and
+for 3.8 in version 24.10.0.
 
 ## Why does my linter or typechecker complain after I format my code?
 

docs/getting_started.md

@@ -16,7 +16,7 @@ Also, you can try out _Black_ online for minimal fuss on the
 
 ## Installation
 
-_Black_ can be installed by running `pip install black`. It requires Python 3.8+ to run.
+_Black_ can be installed by running `pip install black`. It requires Python 3.9+ 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`.

docs/integrations/editors.md

@@ -236,7 +236,7 @@ Configuration:
 
 #### Installation
 
-This plugin **requires Vim 7.0+ built with Python 3.8+ support**. It needs Python 3.8 to
+This plugin **requires Vim 7.0+ built with Python 3.9+ support**. It needs Python 3.9 to
 be able to run _Black_ inside the Vim process which is much faster than calling an
 external command.