Merge branch 'main' into confine-precommit-to-stages

.github/workflows/diff_shades.yml

@@ -22,7 +22,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
-          python-version: "*"
+          python-version: "3.11"
 
       - name: Install diff-shades and support dependencies
         run: |
@@ -59,7 +59,7 @@ jobs:
 
       - uses: actions/setup-python@v4
         with:
-          python-version: "*"
+          python-version: "3.11"
 
       - name: Install diff-shades and support dependencies
         run: |

.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@c6c9a1a66007646a28c153e2a8580a5bad27bcfa
+        uses: peter-evans/create-or-update-comment@23ff15729ef2fc348714a3bb66d2f655ca9066f2
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ steps.metadata.outputs.pr-number }}

.github/workflows/doc.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Set up latest Python
         uses: actions/setup-python@v4
         with:
-          python-version: "*"
+          python-version: "3.11"
 
       - name: Install dependencies
         run: |

.github/workflows/lint.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Set up latest Python
         uses: actions/setup-python@v4
         with:
-          python-version: "*"
+          python-version: "3.11"
 
       - name: Install dependencies
         run: |

CHANGES.md

@@ -12,11 +12,14 @@
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
+- Multiline dictionaries and lists that are the sole argument to a function are now
+  indented less (#3964)
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
+- Add support for single-line format skip with other comments on the same line (#3959)
+
+- Fix a bug in the matching of absolute path names in `--include` (#3976)
 
 ### Packaging
 
@@ -50,6 +53,32 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+## 23.10.1
+
+### Highlights
+
+- Maintenance release to get a fix out for GitHub Action edge case (#3957)
+
+### Preview style
+
+- Fix merging implicit multiline strings that have inline comments (#3956)
+- Allow empty first line after block open before a comment or compound statement (#3967)
+
+### Packaging
+
+- Change Dockerfile to hatch + compile black (#3965)
+
+### Integrations
+
+- The summary output for GitHub workflows is now suppressible using the `summary`
+  parameter. (#3958)
+- Fix the action failing when Black check doesn't pass (#3957)
+
+### Documentation
+
+- It is known Windows documentation CI is broken
+  https://github.com/psf/black/issues/3968
+
 ## 23.10.0
 
 ### Stable style
@@ -71,7 +100,7 @@
 
 ### Parser
 
-- Fix bug where attributes named `type` were not acccepted inside `match` statements
+- Fix bug where attributes named `type` were not accepted inside `match` statements
   (#3950)
 - Add support for PEP 695 type aliases containing lambdas and other unusual expressions
   (#3949)
@@ -929,7 +958,7 @@ and the first release covered by our new
   [`master`](https://github.com/psf/black/tree/main) branch with the
   [`main`](https://github.com/psf/black/tree/main) branch. Some additional changes in
   the source code were also made. (#2210)
-- Sigificantly reorganized the documentation to make much more sense. Check them out by
+- Significantly reorganized the documentation to make much more sense. Check them out by
   heading over to [the stable docs on RTD](https://black.readthedocs.io/en/stable/).
   (#2174)
 

Dockerfile

@@ -3,12 +3,14 @@ FROM python:3.11-slim AS builder
 RUN mkdir /src
 COPY . /src/
 ENV VIRTUAL_ENV=/opt/venv
+ENV HATCH_BUILD_HOOKS_ENABLE=1
+# Install build tools to compile black + dependencies
+RUN apt update && apt install -y build-essential git python3-dev
 RUN python -m venv $VIRTUAL_ENV
-RUN . /opt/venv/bin/activate && pip install --no-cache-dir --upgrade pip setuptools wheel \
-    # Install build tools to compile dependencies that don't have prebuilt wheels
-    && apt update && apt install -y git build-essential \
-    && cd /src \
-    && pip install --no-cache-dir .[colorama,d]
+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]
 
 FROM python:3.11-slim
 

action.yml

@@ -27,6 +27,10 @@ inputs:
     description: 'Python Version specifier (PEP440) - e.g. "21.5b1"'
     required: false
     default: ""
+  summary:
+    description: "Whether to add the output to the workflow summary"
+    required: false
+    default: true
 branding:
   color: "black"
   icon: "check-circle"
@@ -35,6 +39,9 @@ runs:
   steps:
     - name: black
       run: |
+        # Even when black fails, do not close the shell
+        set +e
+
         if [ "$RUNNER_OS" == "Windows" ]; then
           runner="python"
         else
@@ -47,10 +54,12 @@ runs:
         # Display the raw output in the step
         echo "${out}"
 
-        # Display the Markdown output in the job summary
-        echo "\`\`\`python" >> $GITHUB_STEP_SUMMARY
-        echo "${out}" >> $GITHUB_STEP_SUMMARY
-        echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+        if [ "${{ inputs.summary }}" == "true" ]; then
+          # Display the Markdown output in the job summary
+          echo "\`\`\`python" >> $GITHUB_STEP_SUMMARY
+          echo "${out}" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+        fi
 
         # Exit with the exit-code returned by Black
         exit ${exit_code}

docs/guides/introducing_black_to_your_project.md

@@ -18,7 +18,8 @@ previous revision that modified those lines.
 
 So when migrating your project's code style to _Black_, reformat everything and commit
 the changes (preferably in one massive commit). Then put the full 40 characters commit
-identifier(s) into a file.
+identifier(s) into a file usually called `.git-blame-ignore-revs` at the root of your
+project directory.
 
 ```text
 # Migrate code style to Black

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

docs/the_black_code_style/current_style.md

@@ -8,12 +8,14 @@ deliberately limited and rarely added. Previous formatting is taken into account
 little as possible, with rare exceptions like the magic trailing comma. The coding style
 used by _Black_ can be viewed as a strict subset of PEP 8.
 
-_Black_ reformats entire files in place. It doesn't reformat lines that end with
+_Black_ reformats entire files in place. It doesn't reformat lines that contain
 `# fmt: skip` or blocks that start with `# fmt: off` and end with `# fmt: on`.
-`# fmt: on/off` must be on the same level of indentation and in the same block, meaning
-no unindents beyond the initial indentation level between them. It also recognizes
-[YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
-courtesy for straddling code.
+`# fmt: skip` can be mixed with other pragmas/comments either with multiple comments
+(e.g. `# fmt: skip # pylint # noqa`) or as a semicolon separated list (e.g.
+`# fmt: skip; pylint; noqa`). `# fmt: on/off` must be on the same level of indentation
+and in the same block, meaning no unindents beyond the initial indentation level between
+them. It also recognizes [YAPF](https://github.com/google/yapf)'s block comments to the
+same effect, as a courtesy for straddling code.
 
 The rest of this document describes the current formatting style. If you're interested
 in trying out where the style is heading, see [future style](./future_style.md) and try
@@ -176,7 +178,7 @@ If you use Flake8, you have a few options:
    extend-ignore = E203, E501, E704
    ```
 
-   The rationale for E950 is explained in
+   The rationale for B950 is explained in
    [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings).
 
 2. For a minimally compatible config:

docs/the_black_code_style/future_style.md

@@ -113,6 +113,45 @@ my_dict = {
 }
 ```
 
+### Improved multiline dictionary and list indentation for sole function parameter
+
+For better readability and less verticality, _Black_ now pairs parentheses ("(", ")")
+with braces ("{", "}") and square brackets ("[", "]") on the same line for single
+parameter function calls. For example:
+
+```python
+foo(
+    [
+        1,
+        2,
+        3,
+    ]
+)
+```
+
+will be changed to:
+
+```python
+foo([
+    1,
+    2,
+    3,
+])
+```
+
+You can use a magic trailing comma to avoid this compacting behavior; by default,
+_Black_ will not reformat the following code:
+
+```python
+foo(
+    [
+        1,
+        2,
+        3,
+    ],
+)
+```
+
 ### Improved multiline string handling
 
 _Black_ is smarter when formatting multiline strings, especially in function arguments,
@@ -160,3 +199,67 @@ MULTILINE = """
 foobar
 """.replace("\n", "")
 ```
+
+Implicit multiline strings are special, because they can have inline comments. Strings
+without comments are merged, for example
+
+```python
+s = (
+    "An "
+    "implicit "
+    "multiline "
+    "string"
+)
+```
+
+becomes
+
+```python
+s = "An implicit multiline string"
+```
+
+A comment on any line of the string (or between two string lines) will block the
+merging, so
+
+```python
+s = (
+    "An "  # Important comment concerning just this line
+    "implicit "
+    "multiline "
+    "string"
+)
+```
+
+and
+
+```python
+s = (
+    "An "
+    "implicit "
+    # Comment in between
+    "multiline "
+    "string"
+)
+```
+
+will not be merged. Having the comment after or before the string lines (but still
+inside the parens) will merge the string. For example
+
+```python
+s = (  # Top comment
+    "An "
+    "implicit "
+    "multiline "
+    "string"
+    # Bottom comment
+)
+```
+
+becomes
+
+```python
+s = (  # Top comment
+    "An implicit multiline string"
+    # Bottom comment
+)
+```

docs/usage_and_configuration/black_docker_image.md

@@ -24,6 +24,8 @@ created for all unreleased
 [commits on the `main` branch](https://github.com/psf/black/commits/main). This tag is
 not meant to be used by external users.
 
+From version 23.11.0 the Docker image installs a compiled black into the image.
+
 ## Usage
 
 A permanent container doesn't have to be created to use _Black_ as a Docker image. It's

docs/usage_and_configuration/the_basics.md

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

src/black/__init__.py

@@ -1099,7 +1099,7 @@ def _format_str_once(src_contents: str, *, mode: Mode) -> str:
         for feature in {Feature.PARENTHESIZED_CONTEXT_MANAGERS}
         if supports_feature(versions, feature)
     }
-    normalize_fmt_off(src_node)
+    normalize_fmt_off(src_node, mode)
     lines = LineGenerator(mode=mode, features=context_manager_features)
     elt = EmptyLineTracker(mode=mode)
     split_line_features = {