Merge branch 'main' into dependabot/pip/docs/sphinx-7.0.1

.github/workflows/diff_shades_comment.yml

@@ -41,7 +41,7 @@ jobs:
 
       - name: Create or update PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
-        uses: peter-evans/create-or-update-comment@ca08ebd5dc95aa0cd97021e9708fcd6b87138c9b
+        uses: peter-evans/create-or-update-comment@c6c9a1a66007646a28c153e2a8580a5bad27bcfa
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ steps.metadata.outputs.pr-number }}

.github/workflows/pypi_upload.yml

@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.12.3
+        uses: pypa/cibuildwheel@v2.13.1
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

.github/workflows/test.yml

@@ -103,4 +103,4 @@ jobs:
           python -m pip install -e ".[uvloop]"
 
       - name: Format ourselves
-        run: python -m black --check src/
+        run: python -m black --check .

CHANGES.md

@@ -10,6 +10,11 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Fix a bug where an illegal trailing comma was added to return type annotations using
+  PEP 604 unions (#3735)
+- Fix a bug where multi-line open parenthesis magic comment like `type: ignore` were not
+  correctly parsed (#3740)
+
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
@@ -22,28 +27,44 @@
 
 <!-- Changes to how Black can be configured -->
 
+- The `--workers` argument to Black can now be specified via the `BLACK_NUM_WORKERS`
+  environment variable (#3743)
 - `.pytest_cache`, `.ruff_cache` and `.vscode` are now excluded by default (#3691)
+- Fix black not honouring `pyproject.toml` settings when running `--stdin-filename` and
+  the `pyproject.toml` found isn't in the current working directory (#3719)
 
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Upgrade mypyc from 0.991 to 1.3 (#3697)
+
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
 
+- Add support for the new PEP 695 syntax in Python 3.12 (#3703)
+
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
 
+- Avoid importing `IPython` in a case where we wouldn't need it (#3748)
+
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- Use aware UTC datetimes internally, avoids deprecation warning on Python 3.12 (#3728)
+- Change verbose logging to exactly mirror _Black_'s logic for source discovery (#3749)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->
 
+- The `blackd` argument parser now shows the default values for options in their help
+  text (#3712)
+
 ### Integrations
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
@@ -55,6 +76,9 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+- Updated the _classes_ and _exceptions_ documentation in Developer reference to match
+  the latest ccode base. (#3755)
+
 ## 23.3.0
 
 ### Highlights

docs/contributing/index.md

@@ -24,7 +24,8 @@ not very). This is deliberate. _Black_ aims to provide a consistent style and ta
 opportunities for arguing about style.
 
 Bug reports and fixes are always welcome! Please follow the
-[issue template on GitHub](https://github.com/psf/black/issues/new) for best results.
+[issue templates on GitHub](https://github.com/psf/black/issues/new/choose) for best
+results.
 
 Before you suggest a new feature or configuration knob, ask yourself why you want it. If
 it enables better integration with some workflow, fixes an inconsistency, speeds things

docs/contributing/reference/reference_classes.rst

@@ -3,6 +3,9 @@
 
 *Contents are subject to change.*
 
+Black Classes
+~~~~~~~~~~~~~~
+
 .. currentmodule:: black
 
 :class:`BracketTracker`
@@ -18,6 +21,12 @@
     :members:
     :special-members: __str__, __bool__
 
+:class:`RHSResult`
+-------------------------
+
+.. autoclass:: black.lines.RHSResult
+    :members:
+
 :class:`LinesBlock`
 -------------------------
 
@@ -43,34 +52,149 @@
 .. autoclass:: black.comments.ProtoComment
     :members:
 
+:class:`Mode`
+---------------------
+
+.. autoclass:: black.mode.Mode
+    :members:
+
 :class:`Report`
 ---------------
 
 .. autoclass:: black.report.Report
     :members:
     :special-members: __str__
 
+:class:`Ok`
+---------------
+
+.. autoclass:: black.rusty.Ok
+    :show-inheritance:
+    :members:
+
+:class:`Err`
+---------------
+
+.. autoclass:: black.rusty.Err
+    :show-inheritance:
+    :members:
+
 :class:`Visitor`
 ----------------
 
 .. autoclass:: black.nodes.Visitor
     :show-inheritance:
     :members:
 
-Enums
-=====
+:class:`StringTransformer`
+----------------------------
 
-:class:`Changed`
-----------------
+.. autoclass:: black.trans.StringTransformer
+    :show-inheritance:
+    :members:
 
-.. autoclass:: black.Changed
+:class:`CustomSplit`
+----------------------------
+
+.. autoclass:: black.trans.CustomSplit
+    :members:
+
+:class:`CustomSplitMapMixin`
+-----------------------------
+
+.. autoclass:: black.trans.CustomSplitMapMixin
     :show-inheritance:
     :members:
 
-:class:`Mode`
------------------
+:class:`StringMerger`
+----------------------
 
-.. autoclass:: black.Mode
+.. autoclass:: black.trans.StringMerger
+    :show-inheritance:
+    :members:
+
+:class:`StringParenStripper`
+-----------------------------
+
+.. autoclass:: black.trans.StringParenStripper
+    :show-inheritance:
+    :members:
+
+:class:`BaseStringSplitter`
+-----------------------------
+
+.. autoclass:: black.trans.BaseStringSplitter
+    :show-inheritance:
+    :members:
+
+:class:`StringSplitter`
+-----------------------------
+
+.. autoclass:: black.trans.StringSplitter
+    :show-inheritance:
+    :members:
+
+:class:`StringParenWrapper`
+-----------------------------
+
+.. autoclass:: black.trans.StringParenWrapper
+    :show-inheritance:
+    :members:
+
+:class:`StringParser`
+-----------------------------
+
+.. autoclass:: black.trans.StringParser
+    :members:
+
+:class:`DebugVisitor`
+------------------------
+
+.. autoclass:: black.debug.DebugVisitor
+    :show-inheritance:
+    :members:
+
+:class:`Replacement`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.Replacement
+    :members:
+
+:class:`CellMagic`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.CellMagic
+    :members:
+
+:class:`CellMagicFinder`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.CellMagicFinder
+    :show-inheritance:
+    :members:
+
+:class:`OffsetAndMagic`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.OffsetAndMagic
+    :members:
+
+:class:`MagicFinder`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.MagicFinder
+    :show-inheritance:
+    :members:
+
+Enum Classes
+~~~~~~~~~~~~~
+
+Classes inherited from Python `Enum <https://docs.python.org/3/library/enum.html#enum.Enum>`_ class.
+
+:class:`Changed`
+----------------
+
+.. autoclass:: black.report.Changed
     :show-inheritance:
     :members:
 
@@ -80,3 +204,24 @@ Enums
 .. autoclass:: black.WriteBack
     :show-inheritance:
     :members:
+
+:class:`TargetVersion`
+----------------------
+
+.. autoclass:: black.mode.TargetVersion
+    :show-inheritance:
+    :members:
+
+:class:`Feature`
+------------------
+
+.. autoclass:: black.mode.Feature
+    :show-inheritance:
+    :members:
+
+:class:`Preview`
+------------------
+
+.. autoclass:: black.mode.Preview
+    :show-inheritance:
+    :members:

docs/contributing/reference/reference_exceptions.rst

@@ -5,8 +5,14 @@
 
 .. currentmodule:: black
 
+.. autoexception:: black.trans.CannotTransform
+
 .. autoexception:: black.linegen.CannotSplit
 
-.. autoexception:: black.NothingChanged
+.. autoexception:: black.brackets.BracketMatchError
+
+.. autoexception:: black.report.NothingChanged
+
+.. autoexception:: black.parsing.InvalidInput
 
-.. autoexception:: black.InvalidInput
+.. autoexception:: black.mode.Deprecated

docs/contributing/reference/reference_summary.rst

@@ -3,8 +3,11 @@ Developer reference
 
 .. note::
 
-  The documentation here is quite outdated and has been neglected. Many objects worthy
-  of inclusion aren't documented. Contributions are appreciated!
+  As of June 2023, the documentation of *Black classes* and *Black exceptions*
+  has been updated to the latest available version.
+
+  The documentation of *Black functions* is quite outdated and has been neglected. Many
+  functions worthy of inclusion aren't documented. Contributions are appreciated!
 
 *Contents are subject to change.*
 

docs/faq.md

@@ -57,8 +57,8 @@ _Black_ is timid about formatting Jupyter Notebooks. Cells containing any of the
 following will not be formatted:
 
 - automagics (e.g. `pip install black`)
-- non-Python cell magics (e.g. `%%writeline`). These can be added with the flag
-  `--python-cell-magics`, e.g. `black --python-cell-magics writeline hello.ipynb`.
+- non-Python cell magics (e.g. `%%writefile`). These can be added with the flag
+  `--python-cell-magics`, e.g. `black --python-cell-magics writefile hello.ipynb`.
 - multiline magics, e.g.:
 
   ```python

docs/guides/introducing_black_to_your_project.md

@@ -46,7 +46,6 @@ $ git config blame.ignoreRevsFile .git-blame-ignore-revs
 **The one caveat is that some online Git-repositories like GitLab do not yet support
 ignoring revisions using their native blame UI.** So blame information will be cluttered
 with a reformatting commit on those platforms. (If you'd like this feature, there's an
-open issue for [GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/31423)). This is
-however supported by
-[GitHub](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view),
-currently in beta.
+open issue for [GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/31423)).
+[GitHub supports `.git-blame-ignore-revs`](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view)
+by default in blame views however.

docs/requirements.txt

@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-myst-parser==1.0.0
+myst-parser==2.0.0
 Sphinx==7.0.1
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.19